| wxdialog | ||
|---|---|---|
 | Chapter 11. The wxWidgets-based (WXWN) Components |  |
wxdialog
Description
A wxdialog object is a dialog window on the screen, which the programmer has control over and is used for interacting with the user. Windows of type wxdialog have the appearance of dialog windows in the native system, and can be shown modally, that is in a way which forces the user to respond to them before continuing.
Type Tags
wxcontainer, wxdialogparent
Object Value
wxdialog.new()
Description
Creates a new wxdialog object with the required properties.
Prototype
wxdialog.new (
integer lefttopouterwidthouterheightinnerwidthinnerheightvisibleparentcaptionbarcaptiontextmenubuttonvisbuttoniconbackgroundrgbstdbuttonserror
Parameters
| Parameter | Default value | Type name | Description |
|---|---|---|---|
| left | None | integer | The position of the left side of the dialog window on the screen. |
| top | None | integer | The position of the top edge of the dialog window on the screen. |
| outerwidth | None | integer |
The width of the entire dialog window, including borders, titles, and other
parts which are not used by window content. Either
outerwidth or innerwidth must
be specified, but it is an error to specify both.
|
| outerheight | None | integer |
The height of the entire dialog window, including borders, titles, and other
parts which are not used by window content. Either
outerheight or innerheight
must be specified, but it is an error to specify both.
|
| innerwidth | None | integer |
The width of the useable, inner part of the window, not including borders,
titles, etc., or wxdialogstdbutton buttons, if any.
Either outerwidth or
innerwidth must be specified, but it is an error
to specify both.
|
| innerheight | None | integer |
The height of the useable, inner part of the window, not including borders,
titles, etc., or wxdialogstdbutton buttons, if any.
Either outerheight or
innerheight must be specified, but it is an
error to specify both.
|
| visible | .true | boolean | Determines whether or not the dialog window will be visible on the screen. |
| parent | .nul | type(wxdialogparent) | Gives the parent of the new dialog window, if any. |
| captionbar | .true | boolean |
Determines whether or not the dialog window is to have a caption bar, which is
used to display text and to allow the user to move the window by
dragging it using the mouse. If a window does not have a caption
bar, then it cannot have a menu button or vis button, so these must
not be specified as arguments with the value of
.true (but they can be passed as
.false or omitted).
|
| captiontext | "" | string | The text which is to appear in any caption bar the dialog window has. |
| menubutton | .true | boolean |
Determines whether or not the dialog window is to have a menu button, which
allows the user to access a menu giving the ability to manage the
window, for example to move or 'close' it. A window must have a
caption bar if it to have a menu button, so the
captionbar argument must not be passed as
.false (though it can be passed as
.true or omitted).
|
| visbutton | .true | boolean |
Determines whether or not the dialog window is to have a visibilty button,
allowing the user to make the window invisible, which is often
considered to be 'closing' it. A window must have a caption bar if
it to have a vis button, so the captionbar
argument must not be passed as .false (though it
can be passed as .true or omitted).
|
| icon | None | wxbitmap | The wxbitmap to use as the icon for the new dialog window. It is recommended to use an appropriately sized image for this purpose (16 x 16 pixels). |
| backgroundrgb | The system dependent default dialog window background color | integer | The background color of the new dialog window. It is inadvisable to specify any value for this argument which is not the value of an existing rgb object. |
| stdbuttons | "" | string | Specifies which wxdialogstdbutton buttons, if any, are to be created in the dialog. The buttons will be created to appear in a manner which is appropriate for the platform, and the part of the dialog which displays these buttons will be excluded from the area used for showing dialog content. The string is typically a comma separated list of button names, such as "ok,cancel". The valid button names are "ok", "cancel", "yes", "no" and "help". The name of each button can be used together with the member operator (!) to access the button via the wxdialog object. |
| error | .nul | integer |
Specifies an object which is used to output any error code generated during
creation of the wxdialog object. If
error is not specified or is
.nul then any error which occurs during object
creation will halt the program. If an error object is specified and
an error occurs during object creation then the error code is
output into that object and the new methods
returns .nul.
|
Properties
| Property | Type | Description |
|---|---|---|
| _ | type(*) | This property is provided for use by the user to attach any object of any type to the type in which this property is provided. |
| __ | type(*) | This property is provided for use by the user to attach any object of any type to the type in which this property is provided. It has the additional feature of being marked with the resolve keyword, so that object resolution can continue down this property. |
| backgroundrgb | rgb | Shows the color of the inner part of the dialog window when no content is visible. |
| captionbar | boolean | Indicates whether or not the dialog window has a caption bar. The caption bar is used to display a title for the window, and is also used to move the window by dragging with the mouse. |
| captiontext | string | Contains the text which is displayed in the dialog window's caption bar. A dialog window which doesn't have a caption bar can still have caption text. |
| content | type(wxcontent) | The current content of the dialog window. |
| firststdbutton | wxdialogstdbutton | The first button of type wxdialogstdbutton which was created for this dialog window |
| icon | wxbitmap | The wxbitmap object that is used as the source of the icon for the dialog. |
| innerheight | integer | Gives the height of the useable, inner part of the dialog window, not including borders, titles, etc., and also excluding the area containing any wxdialogstdbutton buttons. |
| innerwidth | integer | Gives the width of the useable, inner part of the dialog window, not including borders, titles, etc., and also excluding the area containing any wxdialogstdbutton buttons. |
| left | integer | Gives the x-position of the left hand side of the dialog window on the screen. |
| menubutton | boolean |
Indicates whether or not the dialog window has a button in the caption bar
which provides the user with access to a menu that allows the window
to be managed, for example to be moved or 'closed'. Not all
combinations of .true and
.false settings for menubutton
and visbutton are possible on all platforms.
|
| modal | boolean | Indicates whether or not the dialog window is currently being shown modally. |
| onmove | event | An event which is triggered when the position of the dialog window is changed by the user. |
| onvisibilitychange | event | An event which is triggered when the user changes the visibility of the dialog window, for example by 'closing' the dialog by clicking the visibility button in the caption bar. |
| outerheight | integer | Gives the height of the entire dialog window, including borders, titles, and other parts which are not used by window content or child windows. |
| outerwidth | integer | Gives the width of the entire dialog window, including borders, titles, and other parts which are not used by window content or child windows. |
| parent | type(wxdialogparent) | The parent of this dialog window. If a dialog window has a parent then it is always shown on top of the parent, though it is not contained within the parent. |
| top | integer | Gives the y-position of the top edge of the dialog window on the screen. |
| type | type | Specifies the wxdialog type object. |
| visbutton | boolean |
Indicates whether or not the dialog window has a button in the caption bar
with which the user can make the window invisible. This is normally
thought of as 'closing' the window. Not all combinations of
.true and .false settings for
menubutton and visbutton are
possible on all platforms.
|
| visible | boolean | Indicates whether or not the dialog window is currently visible on the screen. |
Methods
processmodal()
Description
Makes the dialog window visible on the screen, and processes user input to it modally, i.e. without allowing input to other dialogs or windows in the application. It is an error to call this method when the dialog is already visible, either modally or modelessly. The wxdialog object itself is returned.
Prototype
wxdialogvar.processmodal (
integer timeout
Parameters
| Parameter | Default value | Type name | Description |
|---|---|---|---|
| timeout | 0 | integer |
Specifies an amount of time (in microseconds) for which the method will
continue to show the dialog and process user interaction, unless
the dialog window is made not visible by calling the
setvisible() method with a parameter value of
.false. If a value of .inf
is specified, then user interaction will be processed
indefinitely, or until the dialog is made not visible using the
setvisible() method.
|
setbackgroundrgb()
Description
Sets the background color of the dialog window. The wxdialog
object itself is returned, to allow multiple setting methods to be
put into one expression. It is an error to specify both the
rgb argument and one or more of the
red, green or
blue arguments.
Prototype
wxdialogvar.setbackgroundrgb (
integer rgbredgreenblue
Parameters
| Parameter | Default value | Type name | Description |
|---|---|---|---|
| rgb | The current value of the backgroundrgb
property | integer | The new background color of the dialog. It is inadvisable to specify any value for this argument which is not the value of an existing rgb object. |
| red | The current value of the backgroundrgb.red
property | integer | The red component in the new background color of the window. This must be between 0 and 255 inclusive. |
| green | The current value of the backgroundrgb.green
property | integer | The green component in the new background color of the window. This must be between 0 and 255 inclusive. |
| blue | The current value of the backgroundrgb.blue
property | integer | The blue component in the new background color of the window. This must be between 0 and 255 inclusive. |
setcaptiontext()
Description
Sets the text in the caption bar, if any, of the dialog window. The wxdialog object itself is returned, to allow multiple setting methods to be put into one expression.
Prototype
wxdialogvar.setcaptiontext (
string captiontext
Parameters
| Parameter | Default value | Type name | Description |
|---|---|---|---|
| captiontext | None | string | The text which is to appear in any caption bar the dialog has. |
seticon()
Description
Sets the icon for the dialog. This must be a dialog that has a caption bar,
otherwise an error is returned in the error
parameter. The wxdialog object itself is returned, to
allow multiple setting methods to be put into one expression.
Prototype
wxdialogvar.seticon (
wxbitmap iconerror
Parameters
| Parameter | Default value | Type name | Description |
|---|---|---|---|
| icon | None | wxbitmap | The wxbitmap that should be used as the dialog icon. This should be a bitmap that is 16x16 pixels normally. |
| error | .nul | integer |
Specifies an object that is used to output any error code generated during
execution of the function. If error is not
specified or is .nul then any error which
occurs during object creation will halt the program. If an error
object is specified and an error occurs during execution then the
error code is output into that object.
|
setposition()
Description
Sets the size and/or position of a dialog window. The wxdialog object itself is returned, to allow multiple setting methods to be put into one expression.
Prototype
wxdialogvar.setposition (
integer lefttopouterwidthouterheightinnerwidthinnerheight
Parameters
| Parameter | Default value | Type name | Description |
|---|---|---|---|
| left | The current value of the left property | integer | The new position of the left side of the dialog window on the screen |
| top | The current value of the top property | integer | The new position of the top edge of the dialog window on the screen |
| outerwidth | The current value of the outerwidth property | integer |
The new width of the entire dialog window, including borders, titles, and
other parts which are not used by dialog content or
wxdialogstdbutton buttons. It is an error to specify
both outerwidth and
innerwidth arguments.
|
| outerheight | The current value of the outerheight property | integer |
The new height of the entire dialog window, including borders, titles, and
other parts which are not used by dialog content or
wxdialogstdbutton buttons. It is an error to specify
both outerheight and
innerheight arguments.
|
| innerwidth | The current value of the innerwidth property | integer |
The new width of the useable, inner part of the dialog, not including borders,
titles, etc., and also excluding the area containing any
wxdialogstdbutton buttons. It is an error to specify
both outerwidth and
innerwidth arguments.
|
| innerheight | The current value of the innerheight property | integer |
The new height of the useable, inner part of the dialog, not including
borders, titles, etc., and also excluding the area containing any
wxdialogstdbutton buttons. It is an error to specify
both outerheight and
innerheight arguments.
|
setvisible()
Description
Sets whether or not the dialog window is visible on the screen. The wxdialog object itself is returned, to allow multiple setting methods to be put into one expression.
Prototype
wxdialogvar.setvisible (
boolean visible
Parameters
| Parameter | Default value | Type name | Description |
|---|---|---|---|
| visible | None | boolean | Determines whether or not the window will be visible on the screen. |
wxdialog!
Get
The member operator (!) is used to access the objects of type
wxdialogstdbutton that may have been specified during
the creation of the dialog window. These can be any of
yes, no, ok,
cancel, or help. The member
operator followed by the button name returns a reference to the
button. Attempting to access a button that has not been defined is an
error. As an example, if the standard buttons parameter contains the
string "ok", then the code might look like:
wxdialogvar!ok.
Set
Attempting to assign a reference or a value to a wxdialog object using the ! operator is not supported.