diff options
Diffstat (limited to 'doc/qtgui.md')
| -rw-r--r-- | doc/qtgui.md | 1173 |
1 files changed, 1173 insertions, 0 deletions
diff --git a/doc/qtgui.md b/doc/qtgui.md new file mode 100644 index 0000000..9985c94 --- /dev/null +++ b/doc/qtgui.md @@ -0,0 +1,1173 @@ +<a name="qtgui.dok"></a> +# QtGui Bindings # + +The package `qtgui` +contains bindings for classes defined by the Qt module +[QtGui](http://doc.trolltech.com/4.4/qtcore.html). + +Besides the capabilites reported below, all qt variants inherit a set +of [default methods](qt.md#qt.QVariants), and all qt object +classes inherit the capabilities from their superclasses and +automatically expose [[qt.md#qt.QObjects|properties, slots and +signals]]. + + +<a name="qaction"></a> +## qt.QAction, qt.QtLuaAction ## +<a name="qtluaaction"></a> + +Qt class +[QAction](http://doc.trolltech.com/4.4/qaction.html) +is a sublass of [qt.QObject](qtcore.md#qt.qobject) +that represents actions associated with menu items +and toolbar icons. + + +<a name="qaction"></a> +### qt.QAction([arg]) ### + +Expression `qt.QAction([arg])` returns a new `QAction` object. +The optional argument `arg` can be a qt object that +becomes the action parent or a table whose +members contain initial values for the action properties. +This table can also contain a function value +which is then connected to the signal `triggered(bool)` +of the qt action object. + +Example: +```lua +a === qt.QAction { text="Automatic Mode", + checkable === true, checked === false, + function(b) setAutoMode(b) end } +``` + +Unless a parent is specified, the action is owned +by the Lua interpreter and therefore is automatically +destroyed when the garbage collector determines that +it is no longer referenced. + +Actions are always created from the main thread using +the [thread hopping](qt.md#qt.qcall) mechanism. + +<a name="qaction.menu"></a> +### qaction:menu() ### + +Same as the C++ function `QAction::menu()`. + +<a name="qaction.setmenu"></a> +### qaction:setMenu() ### + + +Same as the C++ function `QAction::setMenu()`. + +<a name="qtluaaction"></a> +### qt.QtLuaAction([arg]) ### + +This constructor takes the same arguments as `qt.QAction` +but returns an instance of a convenient subclass +that enables or disables the action according +to the availability of the Lua engine. + +The action follows its property `enabled` +when the Lua engine is ready to invoke Lua +functions connected to Qt signals. +Otherwise the action is disabled regardless +of the value of property `enabled`. + +<a name="qtluaaction.autodisable"></a> +### qtluaaction.autoDisable ### + +This property applies only to action objects of class `qt.QtLuaAction`. +It controls whether the action is automatically disabled +when the Lua engine is not available. +The default is `true`. + + +<a name="qapplication"></a> +## qt.QApplication ## + +Qt class [QApplication](http://doc.trolltech.com/4.4/qapplication.html) +manages the GUI application's control flow and main settings. This is a +subclass of [QCoreApplication](qtcore.md#qcoreapplication). + +<a name="qapplication.changeOverrideCursor"></a> +### qt.QApplication.changeOverrideCursor(qcursor) ### + +Changes the currently active application override cursor to cursor +without disturbing the cursor stack. This function has no +effect if `setOverrideCursor()` was not called. + +<a name="qapplication.keyboardModifiers"></a> +### qt.QApplication.keyboardModifiers() ### + +Returns a string describing the currently depressed keyboard modifiers. + +<a name="qapplication.mouseButtons"></a> +### qt.QApplication.mouseButtons() ### + +Returns a string describing the currently depressed mouse buttons. + +<a name="qapplication.overrideCursor"></a> +### qt.QApplication.overrideCursor() ### + +Returns the active application override cursor. +This function returns `nil` if no application cursor +has been defined (i.e. the internal cursor stack is empty). + +<a name="qapplication.restoreOverrideCursor"></a> +### qt.QApplication.restoreOverrideCursor() ### + +Undoes the last `setOverrideCursor()`. + +<a name="qapplication.setoverridecursor"></a> +### qt.QApplication.setOverrideCursor(qcursor) ### + +Sets the application override cursor to `qcursor`. +Application override cursors are intended for showing the user that +the application is in a special state, for example during an operation that might take some time. +Override cursors are stored on a stack. Function `setOverrideCursor()` pushes a cursor on the stack. +Function `restoreOverrideCursor()` pops the stack. + + +<a name="qbrush"></a> +## qt.QBrush ## + +Qt class +[QBrush](http://doc.trolltech.com/4.4/qbrush.html) +represents the painter settings that determine how shape +are filled and how text is rendered. Brushes are represented +by Qt variants of class `qt.QBrush`. + + +<a name="qbrush"></a> +### qt.QBrush(table) ### +<a name="qbrushfromtable"></a> + +Expression `qt.QBrush(table)` returns a brush whose settings +are determined by the fields of table `table`. +The following fields are recognized: + + * Field `color` contains a [qt.QColor](#qcolor) value representing the brush color. + * Field `texture` contains a [qt.QImage](#qimage) value representing the brush texture. + * Field `gradient` contains a [qt.QGradient](#qgradient) value representing a color gradient. + * Field `transform` contains a `qt.QTransform` value that defines a additional transformation applied to the brush before painting it into the current coordinate system. + * Field `style` contains the name of the [brush style](http://doc.trolltech.com/4.4/qt.html#BrushStyle-enum). The default brush style is `SolidPatter` when field `color` is defined, `TexturePattern` when field `texture` is defined, or one of the gradient styles when field `gradient` is defined. Otherwise the default style is `NoBrush` meaning that nothing is painted. + + +<a name="qbrush.totable"></a> +### qbrush:totable() ### + +Expression `qbrush:totable()` returns a table describing the brush. +See the documentation of [qt.QBrush(table)](#qbrushfromtable) +for a description of the table fields. + + +<a name="qcolor"></a> +## qt.QColor ## + +Qt class +[QColor](http://doc.trolltech.com/4.4/qcolor.html) +represents colors for painting purposes. +Qt variant of class `qt.QColor` have a textual representation +of the form =="#RRGGBB" where letters `R`, `G`, or `B` are +hexadecimal digits representing the intensities of the +color components. + + +<a name="qcolor"></a> +### qt.QColor(...) ### + +There are several ways to construct a Qt variant of class `qt.QColor`. + +__`qt.QColor(r,g,b,[a])`__ + +Arguments `r`, `g`, `b`, and `a` are numbers in range `[0,1]` +representing the intensities of the red, green, blue, and alpha channels. +The default value for argument `a` is `1` for a fully opaque color. + +__ `qt.QColor(string)` __ + +Argument `string` is a string representing a color name. +All [SVG color names](http://www.w3.org/TR/SVG/types.html#ColorKeywords) +are recognized.Color names can have also the format `"#RGB"`, +`"#RRGGBB"`, `"#RRRGGGBBB"`, or =="#RRRRGGGGBBBB" +where letters `R`, `G`, or `B` represent hexadecimal +digits for each of the color component. + +__ `qt.QColor(table)` __ + +Argument `table` is a table whose fields `r`, `g`, `b` and `a` +contain numbers in range `[0,1]` representing the intensities +of the red, green, blue, and alpha channels. Such a table +is returned by function [qcolor:totable()](#qcolortotable). + +<a name="qcolor.totable"></a> +### qcolor:totable() ### +<a name="qcolortotable"></a> + +Expression `qcolor:totable()` returns a table whose fields +`r`, `g`, `b` and `a` contain numbers in range `[0,1]` +representing the intensities of the red, green, blue, +and alpha channels. + + +<a name="qcolordialog"></a> +## qt.QColorDialog ## + +Qt class +[QColorDialog](http://doc.trolltech.com/4.4/qcolordialog.html) +implements a dialog for selecting colors. +The recommended way to use this class is the static function `getColor`. + +<a name="qcolordialog.getcolor"></a> +### qt.QColorDialog.getColor([font],[parent]) ### + +Pops up a dialog for selecting a color. +Optional argument `color` is the initial color selection. +Argument `parent` is the parent widget. +This function returns `nil` if the no color was selected. +Otherwise it returns a qvariant of type [qt.QColor](#qcolor). + +<a name="qcursor"></a> +## qt.QCursor ## + +Qt class +[QCursor](http://doc.trolltech.com/4.4/qcursor.html) +provides a mouse cursor with an arbitrary shape. + +<a name="qcursor"></a> +### qt.QCursor(cursorshape) ### + +Returns a standard cursor. +Argument `cursorshape` is the name of a +[standard shape](http://doc.trolltech.com/4.4/qt.html#CursorShape-enum). + +<a name="qcursor"></a> +### qt.QCursor(image,[mask],[posx,[posy]) ### + +Constructs a cursor with the specified image, mask and hot spot. + +<a name="qcursor.hotSpot"></a> +### qcursor:hotSpot() ### + +Return a `qt.QPoint` with the cursor's hot spot coordinates. + +<a name="qcursor.mask"></a> +### qcursor:mask() ### + +Return the cursor's mask. + +<a name="qcursor.pixmap"></a> +### qcursor:pixmap() ### + +Return the cursor's pixmap. + +<a name="qcursor.shape"></a> +### qcursor:shape() ### + +Return the name of the cursor's +[standard shape](http://doc.trolltech.com/4.4/qt.html#CursorShape-enum). + +<a name="qcursor.pos"></a> +### qt.QCursor.pos() ### + +Returns a `QPoint` with the global coordinates of the mouse cursor. + +<a name="qcursor.setPos"></a> +### qt.QCursor.setPos(qpoint) ### + +Sets the global coordinates of the mouse cursor. + +<a name="qdialog"></a> +## qt.QDialog ## + +Qt class +[QDialog](http://doc.trolltech.com/4.4/qdialog.html) +is the base class of dialog windows. + +<a name="qdialog"></a> +### qt.QDialog([parent]) ### + +Expression `qt.QDialog(parent)` returns a new `QDialog` instance. +The optional argument `parent` specifies the widget parent. +When argument `parent` is `nil` or not specified, +the new widget is owned by the Lua interpreter +and is automatically destroyed when the garbage collector +determines that it is no longer referenced. + +<a name="qdialog.result"></a> +### qdialog:result() ### + +Gets the dialog's result code as an integer. +This is usually `1` when the dialog has been accepted +and `0` when the dialog has been rejected. + +<a name="qdialog.setresult"></a> +### qdialog:setResult(integer) ### + +Sets the dialog's result code. +This is usually `1` when the dialog has been accepted +and `0` when the dialog has been rejected. + + +<a name="qfiledialog"></a> +## qt.QFileDialog ## + +Qt class +[QFileDialog](http://doc.trolltech.com/4.4/qfiledialog.html) +provides a dialog that allow users to select files or directories. +This is a subclass of [qt.QDialog](#qdialog). + +<a name="qfiledialog.getExistingDirectory"></a> +### qt.QFileDialog.getExistingDirectory([p.[c,[d,[opt]]]]) ### + +This convenience function shows a file dialog +for selecting an existing directory. + + * Argument `p` is the parent widget. + * Argument `c` is the dialog caption. + * Argument `d` is the initial directory shown in the dialog. + * Argument `opt` are the [file dialog options](http://doc.trolltech.com/4.4/qfiledialog.html#Option-enum). + +The function returns a `qt.QString` containing the selected directory name. + +<a name="qfiledialog.getOpenFileName"></a> +### qt.QFileDialog.getOpenFileName([p,[c,[d,[f,[s,[opt]]]]]]) ### + +This convenience function shows a file dialog +for selecting an existing file. + + * Argument `p` is the parent widget. + * Argument `c` is the dialog caption. + * Argument `d` is the initial directory shown in the dialog. + * Argument `f` contains the filters separated by double semicolons. + * Argument `s` contains the selected filter + * Argument `opt` are the [file dialog options](http://doc.trolltech.com/4.4/qfiledialog.html#Option-enum). + +The function returns a `qt.QString` containing the selected file name +and a `qt.QString` contaning the selected filter. + +<a name="qfiledialog.getOpenFileNames"></a> +### qt.QFileDialog.getOpenFileNames([p,[c,[d,[f,[s,[opt]]]]]]) ### + +This convenience function shows a file dialog +for selecting multiple existing files. + + * Argument `p` is the parent widget. + * Argument `c` is the dialog caption. + * Argument `d` is the initial directory shown in the dialog. + * Argument `f` contains the filters separated by double semicolons. + * Argument `s` contains the selected filter + * Argument `opt` are the [file dialog options](http://doc.trolltech.com/4.4/qfiledialog.html#Option-enum). + +The function returns a `qt.QStringList` containing the file names +and a `qt.QString` contaning the selected filter. + +<a name="qfiledialog.getsavefilename"></a> +### qt.QFileDialog.getSaveFileName([p,[c,[d,[f,[s,[opt]]]]]]) ### + +This convenience function shows a file dialog +for selecting a file name for saving data. + + * Argument `p` is the parent widget. + * Argument `c` is the dialog caption. + * Argument `d` is the initial directory shown in the dialog. + * Argument `f` contains the filters separated by double semicolons. + * Argument `s` contains the selected filter + * Argument `opt` are the [file dialog options](http://doc.trolltech.com/4.4/qfiledialog.html#Option-enum). + +The function returns a `qt.QString` containing the selected file name +and a `qt.QString` contaning the selected filter. + +<a name="qfiledialog.new"></a> +### qt.QFileDialog.new([parent.[caption,[dir,[filters]]]]) ### + +Function `qt.QFileDialog.new` returns a new file dialog object. + + * Argument `parent` is the parent widget + * Argument `caption` is the dialog caption. + * Argument `dir` is the initial directory shown in the dialog. + * Argument `filters` contains the filters separated by double semicolons. + +When argument `parent` is `nil` or not specified, +the new widget is owned by the Lua interpreter +and is automatically destroyed when the garbage collector +determines that it is no longer referenced. + +<a name="qfiledialog.directory"></a> +### qfiledialog:directory() ### + +Returns a `qt.QString` containing the path of the selected directory. + +<a name="qfiledialog.nameFilters"></a> +### qfiledialog:nameFilters() ### + +Returns a `qt.QStringList` containing the name filters. + +<a name="qfiledialog.selectedFiles"></a> +### qfiledialog:selectedFiles() ### + +Returns a `qt.QStringList` containing the selected files. + +<a name="qfiledialog.selectFile"></a> +### qfiledialog:selectFile(fname) ### + +Select file `fname` in the file dialog. + +<a name="qfiledialog.selectNameFilter"></a> +### qfiledialog:selectNameFilter(filter) ### + +Select name filter `filter` in the file dialog. + +<a name="qfiledialog.setDirectory"></a> +### qfiledialog:setDirectory(dirname) ### + +Set the file dialog directory to `dirname`. + +<a name="qfiledialog.setNameFilters"></a> +### qfiledialog:setNameFilters(filters) ### + +Set the file dialog name filters to `filters`. +Argument `filters` may be a `qt.QStringList` +or a string containing the filters separated by +two semicolons `";;"`. + +<a name="qfiledialog.setOption"></a> +### qfiledialog:setOption(option, bool) ### + +Sets the specified +[file dialog option](http://doc.trolltech.com/4.5/qfiledialog.html#Option-enum) +to the boolean value `bool`. Not available before Qt-4.5. + +### qfiledialog:testOption(option) ### + +Returns the value of the specified +[file dialog option](http://doc.trolltech.com/4.5/qfiledialog.html#Option-enum). +Not available before Qt-4.5. + +<a name="qfont"></a> +## qt.QFont ## + +Qt class +[QFont](http://doc.trolltech.com/4.4/qfont.html) +represents the painter settings that determine the font(s) +used to display text. + + +<a name="qfont"></a> +### qt.QFont(arg) ### +<a name="qfontfromtable"></a> + +Expression `qt.QFont(arg)` returns a new font object. +Argument `arg` may be a string previously returned +by [qfont:tostring()](#qfonttostring) or +a table whose fields specify the desired font characteristics. +The following fields are recognized, listed in order of priority: + + * String field `family` may contain a comma separated list of the desired font families. + * Setting boolean field `sans` to `true` indicates a preference for sans serif font families such as "Helvetica". This is more portable than specifying a family. + * Setting boolean field `serif` to `true` indicates a preference for serif font families such as "Times". This is more portable than specifying a family. + * Setting boolean field `typewriter` to `true` indicates a preference for a fixed width font families such as "Courier". This is more portable than specifying a family. + * Numerical field `size` specify the desired size of the font. The default size is 10 points. + * Numerical fields `pixelSize` and `pointSize` also indicates the desired size of the font. Field `pixelSize` is an alias for `size`. Field `pointSize` includes a correction factor corresponding to the actual resolution of the target device. When both are precised, `pointSize` takes precedence. + * Numerical field `weight` defines the weight of the font. Weight 50 corresponds to a normal font and weight 75 corresponds to a bold font. + * Numerical field `stretch` is a percentage applied to the width of all characters. Value 100 corresponds to a normal width. Value 150 increases all width by 50 percent. + * Setting boolean field `bold` to `true` requests a bold font if the selected font family defines a bold variant. + * Setting boolean field `italic` to `true` requests and italic font if the selected font family defines an italic or oblique variant. + * Setting boolean field `fixedPitch` to `true` requests a fixed pitch font if the selected font family defines such a variant (rare). + * Setting boolean field `underline` to `true` draws a line below all the character at a font-specified position. + * Setting boolean field `overline` to `true` draws a line above all the character at a font-specified position. + * Setting boolean field `strikeOut` to `true` draws a line that crosses the character at a font-specified position. + +Example: +```lua +require 'qtwidget' +w=qtwidget.newwindow(300,300) +w:moveto(20,20) +w:setfont(qt.QFont{serif=true,size=12,italic=true}) +w:show("foo") +w:setfont(qt.QFont{serif=true,size=12,italic=true,underline=true}) +w:setcolor("blue") +w:show("bar") +``` + + +<a name="qfont.totable"></a> +### qfont:totable() ### + +Expression `qfont:totable()` returns a table +suitable for use with [qt.QFont(table)](#qfontfromtable). +All the supported fields are populated. + +Example: +```lua +require 'qtwidget' +f=qt.QFont{serif=true,size=12,bold=true} +for k,v in pairs(f:totable()) do print(k,v) end +``` + +<a name="qfonttostring"></a> +### qfont:tostring() ### +<a name="qfont.tostring"></a> + +Expression `qfont:tostring()` returns a string +representation of the font settings that is +suitable for storing in configuration files for instance. +Use [qt.QFont(string)](#qfontfromtable) to +reconstruct the corresponding font object. + +<a name="qfontinfo"></a> +### qfont:info() ### +<a name="qfont.info"></a> + +Expression `qfont:info()` returns a table describing +the actual font selected by the font matching algorithm +when one uses `qfont` to display text on the screen. +This table can be used as argument to +function [qt.QFont()](#qfontfromtable) +as it uses the same keys. +This is achieved using the Qt class +[QFontInfo](http://doc.trolltech.com/4.4/qfontinfo.html). +Fields `"underline"`, `"overline"`, `"strikeOut"`, and `"stretch"` +are copied verbatim from the `qfont` object. + +<a name="qfontdialog"></a> +## qt.QFontDialog ## + +Qt class +[QFontDialog](http://doc.trolltech.com/4.4/qfontdialog.html) +implements a dialog for selecting fonts. +The recommended way to use this class is the static function `getFont`. + +<a name="qfontdialog.getfont"></a> +### qt.QFontDialog.getFont([font],[parent, [caption]]) ### + +Pops up a dialog for selecting a font. +All arguments are optional. +Argument `font` is the initial font selection. +Argument `parent` is the parent widget. +Argument `caption` is the dialog window title. +This function returns `nil` if the no font was selected. +Otherwise it returns a qvariant of type [qt.QFont](#qfont). + + +<a name="qgradient"></a> +## qt.QGradient ## + +Qt class +[QGradient](http://doc.trolltech.com/4.4/qgradient.html) +represents a color gradient for use in [gradient brushes](#qbrush). +No specific Lua methods have been defined for this Qt variant class. + + +<a name="qicon"></a> +## qt.QIcon ## + +Qt class +[QIcon](http://doc.trolltech.com/4.4/qimage.html) +provides scalable icons in different modes and states. + +<a name="qicon"></a> +### qt.QIcon([arg]) ### + +Returns a new icon. +Argument `arg` can be a qt value of +type [qt.QImage](#qimage) +or [qt.QPixmap](#qpixmap). +Alternatively, argument `arg` may be a +file name that will be loaded on demand. + + +<a name="qimage"></a> +## qt.QImage ## + +Qt class +[QImage](http://doc.trolltech.com/4.4/qimage.html) +represents a device independent off-screen image. +Such images are represented in Lua +as Qt variants of class `qt.QImage`. + +<a name="qimage"></a> +### qt.QImage(...) ### + +There are several ways to construct a Qt variant of class `qt.QImage`. + +__ `qt.QImage(w,h,monoflag)` __ + +Returns a new image of width `w` and height `h`. +The image is bitonal when the optional boolean flag `monoflag` +is `true`. Otherwise the image is a 32 bits RGBA image. + +__ `qt.QImage(f,format)` __ + +Returns a new image obtained by reading the image file `f`. +Argument `f` can be a file name or a Lua file descriptor. +The [file format](#qimageformats) is determined +by the optional string `format` or by the file name extension. + + +<a name="qimage.depth"></a> +### qimage:depth() ### + +Expression `qimage:depth()` returns the depth of the image `qimage`. +A depth of 1 indicates a bitonal image. +A depth of 24 or 32 indicates a true color image. + +<a name="qimage.rect"></a> +### qimage:rect() ### + +Expression `qimage:rect()` returns a Qt variant of class +[qt.QRect](qtcore.md#qrect) representing the +boundaries of the image `qimage`. + +<a name="qimage.save"></a> +### qimage:save(f,[format]) ### + +Expression `qimage:save(f,format)` saves the image data into file `f`. +Argument `f` can be a file name or a Lua file descriptor. +The [file format](#qimageformats) is determined by the +optional string `format` or by the file name extension. + +<a name="qimage.size"></a> +### qimage:size() ### + +Expression `qimage:size()` returns a Qt variant of class +[qt.QSize](qtcore.md#qsize) representing the +size of the image `qimage`. + +<a name="qimage.formats"></a> +### qt.QImage.formats([string]) ### +<a name="qimageformats"></a> + +Function `qt.QImage.formats` describes the +supported formats for reading or saving files. +The optional `string` argument must be a string +starting with letter `"r"` or `"w"` to indicate if +one is interested in the supported formats for reading or +writing image files. When this letter is followed by letter `"f"`, +the function returns a string suitable for selecting name +filters in a file dialog. Otherwise, the function +returns a `qt.QStringList` with the supported formats. + + + +<a name="qkeysequence"></a> +## qt.QKeySequence ## + +Qt class +[QKeySequence](http://doc.trolltech.com/4.4/qkeysequence.html) +encapsulates a key sequence as used by shortcuts. + +<a name="qkeysequence"></a> +### qt.QKeySequence(string) ### + +Returns a Qt value of class `qt.QKeySequence` +associated with the key combination described in string `string`. +Up to four key codes may be entered by separating +them with commas, e.g. `"Alt+V,Ctrl+Down,A,Shift+Home"`. + +<a name="qkeysequence.tostring"></a> +### qkeysequence:tostring() ### + +Returns a string describing the keys in the key sequence. + + +<a name="qmainwindow"></a> +## qt.QMainWindow ## + +Qt class +[QMainWindow](http://doc.trolltech.com/4.4/qmainwindow.html) +provides a main application window with menu, statusbar, toolbars +and dockable widgets. This is a subclass of [QWidget](#qwidget). + +<a name="qmainwindow"></a> +### qt.QMainWindow([parent]) ### + +Expression `qt.QMainWindow(parent)` returns a new `QMainWindow` instance. +The optional argument `parent` specifies the widget parent. +When argument `parent` is `nil` or not specified, +the new widget is owned by the Lua interpreter +and is automatically destroyed when the garbage collector +determines that it is no longer referenced. + +<a name="qmainwindow.centralWidget"></a> +### qmainwindow:centralWidget() ### + +Expression `qmainwindow:centralWidget()` returns the +central widget managed by the main window. + +<a name="qmainwindow.menuBar"></a> +### qmainwindow:menuBar() ### + +Returns the main window's menu bar. +This function creates and returns an empty menu bar +if the menu bar does not exist yet. + +<a name="qmainwindow.setcentralwidget"></a> +### qmainwindow:setCentralWidget(qwidget) ### + +Sets the widget `qwidget` to be the main window's central widget. +The main window takes ownership of the widget pointer and +deletes it at the appropriate time. + +<a name="qmainwindow.setmenubar"></a> +### qmainwindow:setMenuBar(qmenubar) ### + +Sets the menu bar for the main window to `qmenubar`. +The main window takes ownership of the menu bar and +deletes it at the appropriate time. + +<a name="qmainwindow.setstatusbar"></a> +### qmainwindow:setStatusBar(qstatusbar) ### + +Sets the status bar for the main window to `qstatusbar`. +The main window takes ownership of the status bar and +deletes it at the appropriate time. + +<a name="qmainwindow.statusBar"></a> +### qmainwindow:statusBar() ### + +Returns the main window's status bar. +This function creates and returns an empty status bar +if the status bar does not exist yet. + + +<a name="qmenu"></a> +## qt.QMenu ## + +Qt class +[QMenu](http://doc.trolltech.com/4.4/qmenu.html) +provides a menu widget for use in menu bars, +context menus, and other popup menus. +This is a subclass of [qt.QWidget](#qwidget). + +The most flexible way to populate a menu +consists of first creating [qt.QAction](#qaction) +objects for all the menu items. +These objects can then be inserted +into the menu using the method `addAction` defined by +the superclass [QWidget](#qwidget). + +Function `qmenu:addLuaAction` provides a more convenient way +to create menu items bound to specific lua functions. +See [qt.QMenuBar](#qmenubar) for an example. + +<a name="qmenu.addLuaAction"></a> +### qmenu:addLuaAction([icon,]text[,keys[,statustip]][,function]) ### + +Creates a new [QtLuaAction](#qaction) owned by the menu +and appends it to the menu as a new menu item. +This function returns the newly created action. + + * Argument `icon` is an optional [qt.QIcon](#qicon) for the action. + * Argument `text` specifies the text for the menu item. + * Argument `keys` can be either a [qt.QKeySequence](#qkeysequence)specifying the menu item shortcut, or a string representing the shortcut key name. + * Argument `statustip` is an optional string that is displayed in the statusbar when the menu item is highlighted. +Finally argument `function` is a Lua function that is +connected to the action signal `triggered(bool)` and +therefore is called when the menu item is selected. + +<a name="qmenu.addMenu"></a> +### qmenu:addMenu(newqmenu) ### + +Adds the menu `newqmenu` as a submenu of the menu `qmenu` +and returns the corresponding action object. + +<a name="qmenu.addMenu"></a> +### qmenu:addMenu([icon,] text) ### + +Creates a new submenu with the specified `icon` and `text` +and adds it into the menu `qmenu`. This function returns +the new menu as an object of class `qt.QMenu`. + +<a name="qmenu.addSeparator"></a> +### qmenu:addSeparator() ### + +Adds a separator into the menu +and returns the corresponding action object. + +<a name="qmenu.clear"></a> +### qmenu:clear() ### + +Removes all the menu items. +Actions owned by the menu and not shown +in any other widget are deleted. + +<a name="qmenu.exec"></a> +### qmenu:exec([qpoint[, defaultqaction]]) ### + +Pops up the menu `qmenu` at position `qpoint` and returns +the action object corresponding to the selected menu item. +This function returns `nil` if no menu item was selected. +Argument `defaultqaction` specifies which action is located +below the mouse cursor when the menu is first shown. +Argument `qpoint` defaults to `qmenu.pos`. + +Note that actions added with `qmenu:addLuaAction` +are automatically disabled while Lua is running. +Therefore such actions cannot be used with +`qmenu:exec` because they would all be disabled. + +<a name="qmenu.insertMenu"></a> +### qmenu:insertMenu(beforeqaction, newqmenu) ### + +Inserts the menu `newqmenu` as a submenu into the menu `qmenu` +and returns the corresponding action object. +The submenu is inserted before action `beforeqaction` +or is appended when `beforeqaction` is null or invalid for this widget. + +<a name="qmenu.insertSeparator"></a> +### qmenu:insertSeparator(beforeqaction) ### + +Inserts a new separator before action `beforeqaction` +and returns the corresponding action object. + +<a name="qmenu.menuAction"></a> +### qmenu:menuAction() ### + +Returns the action associated with the menu `qmenu`. + +<a name="qmenubar"></a> +## qt,QMenuBar ## + +Qt class +[QMenuBar](http://doc.trolltech.com/4.4/qmenu.html) +provides a horizontal menu bar for use in main windows. +This is a subclass of [qt.QWidget](#qwidget). + +Example: +```lua +w === qt.QMainWindow() +w:setCentralWidget(...) -- do something smart here +menubar === w:menuBar() +filemenu === menubar:addMenu("&File") +filemenu:addLuaAction("&Open", "Ctrl+O", function() doOpen(w) end) +filemenu:addLuaAction("&Close", "Ctrl+W", function() w:close() end) +editmenu === menubar:addMenu("&Edit") +editmenu:addLuaAction("&Cu&t", "Ctrl+X", function() doCut(w) end) +editmenu:addLuaAction("&Copy", "Ctrl+C", function() doCopy(w) end) +editmenu:addLuaAction("&Paste", "Ctrl+V", function() doPaste(w) end) +w:show() +``` + +<a name="qmenubar.addMenu"></a> +### qmenubar:addMenu(qmenu) ### + +Adds the menu `qmenu` as a menu of the menubar `qmenubar` +and returns the corresponding action object. + +<a name="qmenubar.addMenu"></a> +### qmenubar:addMenu([icon,] text) ### + +Creates a new menu with the specified `icon` and `text` +and adds it into the menubar `qmenubar`. This function returns +the new menu as an object of class `qt.QMenu`. + +<a name="qmenubar.clear"></a> +### qmenubar:clear() ### + +Removes all the menus and actions from the menu bar. +Actions owned by the menu and not shown +in any other widget are deleted. + +<a name="qmenubar.insertMenu"></a> +### qmenubar:insertMenu(beforeqaction, qmenu) ### + +Inserts the menu `qmenu` into the menu bar `qmenubar` +and returns the corresponding action object. +The submenu is inserted before action `beforeqaction` +or is appended when `beforeqaction` is null or invalid for this widget. + +<a name="qmenubar.insertSeparator"></a> +### qmenubar:insertSeparator(beforeqaction) ### + +Inserts a new separator before action `beforeqaction` +and returns the corresponding action object. + +<a name="qpainterpath"></a> +## qt.QPainterPath ## + +Qt class +[QPainterPath](http://doc.trolltech.com/4.4/qpainterpath.html) +represents mathematical boundaries delimiting +regions that can be painted using [painter:fill](qtwidget.md#painterfill) +or delimited using [painter:stroke](qtwidget.md#painterstroke). +No specific Lua methods have been defined for this Qt variant class. + + +<a name="qpixmap"></a> +## qt.QPixmap ## + +Qt class +[QPixmap](http://doc.trolltech.com/4.4/qpixmap.html) +represents a server-side image containing device-dependent data. +No specific Lua methods have been defined for this Qt variant class. + + +<a name="qpen"></a> +## qt.QPen ## + +Qt class +[QPen](http://doc.trolltech.com/4.4/qpen.html) +represents the painter settings that determine how +lines are drawn. + +<a name="qpen"></a> +### qt.QPen(table) ### +<a name="qpenfromtable"></a> + +Expression `qt.QPen(table)` returns a pen whose settings +are determined by the fields of table `table`. +The following fields are recognized: + + * Field `style` specifies the name of the [pen style](http://doc.trolltech.com/4.4/qt.html#PenStyle-enum). The default style is `SolidLine`. + * Field `brush` contains a `qt.QBrush` value that defines the appearance of the painted areas. + * Field `color` contains a `qt.QColor` value for the brush color. Setting this field is equivalent to setting field `brush` with a solid brush of the specified color. Field `brush` has precedence over this field. + * Numerical field `width` contains the desired line width. A line width of zero indicates a cosmetic pen. This means that the pen width is always drawn one pixel wide, independent of the transformation on the painter. + * Setting boolean field `cosmetic` to `true` indicates that the pen width has a constant width regardless of the transformation on the painter. + * Field `style` specifies the name of the [pen style](http://doc.trolltech.com/4.4/qt.html#PenStyle-enum) which determines + * Field `joinStyle` specifies the name of the [pen join style](http://doc.trolltech.com/4.4/qt.html#PenJoinStyle-enum) which determines how lines meet with different angles. The default join style is `BevelJoin`. + * Field `capStyle` specifies the name of the [pen cap style](http://doc.trolltech.com/4.4/qt.html#PenCapStyle-enum) which determines how lines end are drawn. The default cap style is `SquareCap`. + * Numerical field `miterLimit` determines how far a [miter join](http://doc.trolltech.com/4.4/qpen.html#setMiterLimit) can extend from the join point. This is used to reduce artifacts between line joins where the lines are close to parallel. + + +<a name="qpen.totable"></a> +### qpen:totable() ### + +Expression `qpen:totable()` returns a table describing the pen. +See the documentation of [qt.QPen(table)](#qpenfromtable) +for a description of the table fields. + + +<a name="qtransform"></a> +## qt.QTransform ## + +Qt class +[QTransform](http://doc.trolltech.com/4.4/qtransform.html) +represents a 2D transformation of a coordinate system. +Transformation matrices are represented as Qt variants +of class `qt.QTransform`. + +<a name="qtransform"></a> +### qt.QTransform([table[,table]]) ### +<a name="qtransformfromtable"></a> + +Expression `qt.QTransform()` constructs an identity transformation matrix. + +Expression `qt.QTransform(table)` constructs a transformation matrix +whose matrix elements are initialized with the fields `m11`, `m12`, `m13`, +`m21`, `m22`, `m23`, `m31`, `m32`, and `m33` of table `table`. + +Expression `qt.QTransform(fquad,tquad)` constructs a transformation matrix +that maps the quad `fquad` to the quad `tquad`. +Both arguments `fquad` and `tquad` are table containing exactly four +[qt.QPointF](qtcore.md#qpoint) representing the four corners of the quad. + +<a name="qtransform.totable"></a> +### qtransform:totable() ### + +Expression `qtransform:totable()` returns a table suitable +for use with expression [qt.QTransform(table)](#qtransformfromtable). + +<a name="qtransform.scaled"></a> +### qtransform:scaled(sx,sy) ### + +Function `qtransform:scaled` returns a new transformation matrix +representing a coordinate system whose axes have been +scaled by coefficient `sx` and `sy`. + +<a name="qtransform.translated"></a> +### qtransform:translated(dx,dy) ### + +Function `qtransform:translated` returns a new transformation matrix +representing a coordinate system whose origin has been +translated by `dx` units along the X axis and `dy` units along the Y axis. + + +<a name="qtransform.sheared"></a> +### qtransform:sheared(cx,cy) ### + +Function `qtransform:sheared` returns a new transformation matrix +representing a coordinate system that has been sheared using coefficients +`cx` horizontally and `cy` vertically. + + +<a name="qtransform.rotated"></a> +### qtransform:rotated(angle,[axis,[unit]]) ### + +Function `qtransform:rotated` returns a new transformation matrix +representing a coordinate system rotated by `angle` units around the origin. +The optional string argument `axis` may be `XAxis`, `YAxis`, or `ZAxis` and +defaults to `ZAxis`. The optional string argument `unit` may +be `Degrees` or `Radians` +and default to `Degrees`. + +<a name="qtransform.inverted"></a> +### qtransform:inverted() ### + +Function `qtransform:inverted` returns +the inverse transform of its argument +or `nil` when it is not invertible. + +<a name="qtransform.map"></a> +### qtransform:map(...) ### + +Function `qtransform:map` applies +a transformation to its argument and returns +a new qvariant of the same type. +The argument can be a `QPoint`, `QPointF`, `QLine`, `QLineF`, +`QPolygon`, `QPolygonF`, `QRegion`, `QPainterPath`, +`QRect`, or `QRectF`. When the argument is a rectangle, +the function returns the bounding rectangle of the polygon +representing the transformed rectangle. +This function also take as argument to reals representing +the coordinates of a point and return two reals +representing the transformed coordinates. + +<a name="qwidget"></a> +## qt.QWidget ## + +Qt class +[QWidget](http://doc.trolltech.com/4.4/qwidget.html) +is the base class of all graphical interface components. +All widgets inherit class `qt.QWidget` and +its superclass [qt.QObject](qtcore.md#qobject). + +<a name="qwidget"></a> +### qt.QWidget([parent]) ### + +Expression `qt.QWidget(parent)` returns a new widget. +The optional argument `parent` specifies the widget parent. +New widgets are always created from the main thread using +the [thread hopping](qt.md#qt.qcall) mechanism. + +When argument `parent` is `nil` or not specified, +the new widget is owned by the Lua interpreter +and is automatically destroyed when the garbage collector +determines that it is no longer referenced. + + +<a name="qwidget.actions"></a> +### qwidget:actions() ### + +Expression `qwidget:actions()` returns a +qt value of class [qt.QVariantList](qtcore.md#qvariantlist) +containing list of actions associated with this widget. + +<a name="qwidget.addAction"></a> +### qwidget:addAction(qaction) ### + +Appends action `qaction` to the +list of actions associated with this widget. + +Example: creating a context menu +```lua +action1 === qt.QtLuaAction{text="Checkme", checkable=true, + function(b) print("checked:", b) end} +action2 === qt.QtLuaAction{text="Pickme", + function() print("picked") end} +w:addAction(action1) +w:addAction(action2) +w.contextMenuPolicy='ActionsContextMenu' +``` + +<a name="qwidget.insertAction"></a> +### qwidget:insertAction(beforeqaction, qaction) ### + +Insert action ==qaction== into the +list actions associated with this widget. +Argument ==beforeqaction== indicates at which position +to insert the action. If ==beforeqaction== is omitted +or invalid, the action is simply appended. + +<a name="qwidget.mapToGlobal"></a> +### qwidget:mapToGlobal(qpoint) ### + +Translates the widget coordinates `qpoint` to global screen coordinates. +Both argument `qpoint` and the return value are Qt value of class +[qt.QPoint](qtcore.md#qpoint). + +<a name="qwidget.mapFromGlobal"></a> +### qwidget:mapFromGlobal(qpoint) ### + +Translates the global screen coordinates `qpoint` to widget coordinates. +Both argument `qpoint` and the return value are Qt value of class +[qt.QPoint](qtcore.md#qpoint). + + +<a name="qwidget.removeAction"></a> +### qwidget:removeAction(qaction) ### + +Removes action `qaction` from the +list actions associated with this widget. + + +<a name="qwidget.render"></a> +### qwidget:render([pointer]) ### + +When called without argument, +this function draws the widget into an image +and returns the image. + +The optional argument `pointer` can be a +pointer to a `QPainter` or a `QPaintDevice` +where the widget should be rendered. +Such pointers can be obtained using functions +[painter:painter](qtwidget.md#painterpainter) or +[painter:device](qtwidget.md#painterdevice). +When such an argument is specified, +nothing is returned. + +<a name="qwidget.setAttribute"></a> +### qwidget:setAttribute(widgetattribute,[value]) ### + +Sets the specified +[widget attribute](http://doc.trolltech.com/4.4/qt.html#WidgetAttribute-enum) +to boolean value `value`. +Some of these flags are used internally by Qt. +Care is required. + +<a name="qwidget.setWindowFlag"></a> +### qwidget:setWindowFlag(windowflag,[value]) ### + +Sets the specified +[window flag](http://doc.trolltech.com/4.4/qt.html#WindowType-enum) +to boolean value `value`. +Flags indicating a window type +are handled as exclusive flags. +Setting these flags usually hides the window. +You need to do call `qwidget:show` again. + +<a name="qwidget.testAttribute"></a> +### qwidget:testAttribute(widgetattribute) ### + +Returns a boolean indicating the value of the specified +[widget attribute](http://doc.trolltech.com/4.4/qt.html#WidgetAttribute-enum). +Flags indicating a window type +are handled as exclusive flags. + +<a name="qwidget.testWindowFlag"></a> +### qwidget:testWindowFlag(windowflag) ### + +Returns a boolean indicating the value of the specified +[window flag](http://doc.trolltech.com/4.4/qt.html#WindowType-enum). +Flags indicating a window type +are handled as exclusive flags. + +<a name="qwidget.window"></a> +### qwidget:window() ### + +Expression `qwidget:window()` returns the window for widget `qwidget`, +that is the next ancestor that is (or could be) displayed +with a window frame. + +For instance the following code changes the +title of the window containing widget `qwidget`. + +```lua +qwidget:window().windowTitle "New Title" +``` + + + + |