| wxwindow | ||
|---|---|---|
 | Chapter 11. The wxWidgets-based (WXWN) Components |  |
wxwindow
Description
A wxwindow object is a window on the screen, which the programmer
has control over and is used for interacting with the user. It can either
be a top-level frame window or a child window. Child windows are
primarily useful for creating various panels in a frame window. Child
windows cannot have a caption bar, so can't have system menus, min
buttons, max buttons or close (visibility) buttons. It is an error to
pass values to wxwindow.new() that try to create a child window with a
caption bar, a system menu, a min button, a max button, a close button,
that is minimized, or that is maximized. Child windows cannot have a
menubar, toolbar or statusbar, so can't be passed to the
setwindow() method of any of these. These are
limitations of wxWidgets.
![[Note]](images/note.png) | Note |
|---|---|
Child windows are not held in a ring hanging off the parent. If you don't hang onto the window reference yourself then the window vanishes. |
Type Tags
wxcontainer, wxdialogparent, wxwindowparent
Object Value
wxwindow.new()
Description
Creates a new wxwindow object with the required properties.
Prototype
wxwindow.new (
integer lefttopouterwidthouterheightinnerwidthinnerheightvisibleminimizedmaximizedparentcaptionbarcaptiontextmenubuttonminbuttonmaxbuttonvisbuttoniconvscrollbarhscrollbarborderbackgroundrgberror
Parameters
| Parameter | Default value | Type name | Description |
|---|---|---|---|
| left | None | integer | The position of the left side of the window either relative to its parent window, if any, or on the screen. |
| top | None | integer | The position of the top edge of the window either relative to its parent window, if any, or on the screen. |
| outerwidth | None | integer |
The width of the entire window, including borders, titles, and other parts
which are not used by window content or child windows. Either
outerwidth or innerwidth must
be specified, but it is an error to specify both.
|
| outerheight | None | integer |
The height of the entire window, including borders, titles, and other parts
which are not used by window content or child windows. 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. 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. Either outerheight or
innerheight must be specified, but it is an
error to specify both.
|
| visible | .true | boolean | Determines whether or not the window will be visible on the screen. |
| minimized | .false | boolean |
Determines whether or not the window is to be displayed in a minimized state
(also known as iconized). It is an error for both
minimized and maximized
arguments to be specified as .true. If both
minimized and maximized
arguments are specified as .false then the
window will be created in a restored or 'normal' state.
|
| maximized | .false | boolean |
Determines whether or not the window is to be displayed in a maximized state,
i.e. expanded to cover the whole available display. It is an error
for both minimized and
maximized arguments to be specified as
.true. If both minimized and
maximized arguments are specified as
.false then the window will be created in a
restored or 'normal' state.
|
| parent | None | type(*) | This contains the reference to a wxwindow object that is the parent of a child window. It is an error to pass values to wxwindow.new() that try to create a child window with a caption bar, a system menu, a min button, a max button, a close button, that is minimized, or that is maximized. |
| captionbar | .true | boolean |
Determines whether or not the 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, min button, max 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 window has. |
| menubutton | .true | boolean |
Determines whether or not the 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 minimize or maximize 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).
|
| minbutton | .true | boolean |
Determines whether or not the window is to have a minimize button, which
allows the user to minimize the window. A window must have a
caption bar if it to have a min button, so the
captionbar argument must not be passed as
.false (though it can be passed as
.true or omitted).
|
| maxbutton | .true | boolean |
Determines whether or not the window is to have a maximize button, which
allows the user to maximize the window. A window must have a
caption bar if it to have a max 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 window is to have a visibilty button, which
allows 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 window. It is recommended to use an appropriately sized image for this purpose (16 x 16 pixels). |
| vscrollbar | .false | boolean |
Determines whether the window has a vertical scroll bar to allow the user to
scroll the content of the window up or down. If this is
.false then the window never has a vertical
scroll bar. If this is .true then the window has
a vertical scroll bar if the size of the content exceeds the size
of the inner part of the window in the vertical direction,
otherwise it does not have a vertical scroll bar.
|
| hscrollbar | .false | boolean |
Determines whether the window has a horizontal scroll bar to allow the user to
scroll the content of the window right or left. If this is
.false then the window never has a horizontal
scroll bar. If this is .true then the window has
a horizontal scroll bar if the size of the content exceeds the size
of the inner part of the window in the horizontal direction,
otherwise it does not have a horizontal scroll bar.
|
| border | "sizeable" | string |
Determines what type of border with which the window is created and in
association with that, whether the window is sizeable or not. The
options are "simple",
"sizeable", "none",
"sunken", and "raised" with
"sizeable" being the default value for top level
windows and "simple" the default for child
windows.
|
| backgroundrgb | The system dependent default window background color | integer | The background color of the new window. It is inadvisable to specify any value for this argument which is not the value of an existing rgb object. |
| error | .nul | integer |
Specifies an object which is used to output any error code generated during
creation of the wxwindow 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 window when no content is visible. |
| border | string | This setting determines the type of window border that will be used and that will in turn decide whether the window can be resized or not. For a resizeable window use "sizeable", for a window that can't be resized, use the value "simple". |
| captionbar | boolean | Indicates whether or not the 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 a window's caption bar. A window which doesn't have a caption bar can still have caption text. This is the text which will be displayed if the window is changed so that it does have a caption bar. |
| content | type(wxcontent) | The current content of the window. |
| hscrollbar | boolean |
Indicates whether the window has a horizontal scroll bar to allow the user to
scroll the content of the window left or right. If this is set to
.false then the window never has a horizontal
scroll bar. If this is set to .false then the
window has a horizontal scroll bar if the size of the content exceeds
the size of the inner part of the window in the horizontal direction,
otherwise it does not have a horizontal scroll bar.
|
| icon | wxbitmap | The wxbitmap object that is used as the source of the icon for the window. |
| innerheight | integer | Gives the height of the useable, inner part of the window, not including borders, titles, etc. |
| innerwidth | integer | Gives the width of the useable, inner part of the window, not including borders, titles, etc. |
| left | integer | Gives the x-position of the left hand side of the window on the screen. |
| maxbutton | boolean |
Indicates whether or not the window has a button in the caption bar with which
the user can maximize the window. Not all combinations of
.true and .false settings for
menubutton, minbutton,
maxbutton and visbutton are
possible on all platforms.
|
| maximized | boolean | Indicates whether or not the window is currently maximized. A window cannot be both minimized and maximized at the same time. |
| menubar | wxmenubar | A reference to the menu bar object (if there is one) for the window. |
| menubutton | boolean |
Indicates whether or not the 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 minimized or maximized. Not all
combinations of .true and
.false settings for menubutton,
minbutton, maxbutton and
visbutton are possible on all platforms.
|
| minbutton | boolean |
Indicates whether or not the window has a button in the caption bar with which
the user can minimize the window. Not all combinations of
.true and .false settings for
menubutton, minbutton,
maxbutton and visbutton are
possible on all platforms.
|
| minimized | boolean | Indicates whether or not the window is currently minimized. A window cannot be both minimized and maximized at the same time. |
| onmove | event | An event which is triggered when the position of the window is changed by the user. |
| onsize | event | An event which is triggered when the size of the window is changed by the user. |
| onstatechange | event | An event which is triggered when the user changes the state of the window, for example by minimizing or maximizing the window. |
| onvisibilitychange | event | An event which is triggered when the user changes the visibility the window, for example by 'closing' the window by clicking the visibility button in the caption bar. |
| outerheight | integer | Gives the height of the entire 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 window, including borders, titles, and other parts which are not used by window content or child windows. |
| parent | type(*) | This contains a reference to the parent window of a child window. |
| statusbar | wxstatusbar | A reference to the status bar object (if there is one) for the window. |
| toolbar | wxtoolbar | A reference to the tool bar object (if there is one) for the window. |
| top | integer | Gives the y-position of the top edge of the window on the screen. |
| type | type | Specifies the wxwindow type object. |
| visbutton | boolean |
Indicates whether or not the 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, minbutton,
maxbutton and visbutton are
possible on all platforms.
|
| visible | boolean | Indicates whether or not the window is currently visible on the screen. |
| vscrollbar | boolean |
Indicates whether the window has a vertical scroll bar to allow the user to
scroll the content of the window up or down. If this is set to
.false then the window never has a vertical scroll
bar. If this is set to .false then the window has
a vertical scroll bar if the size of the content exceeds the size of
the inner part of the window in the vertical direction, otherwise it
does not have a vertical scroll bar.
|
Methods
getscrollpositions()
Description
Retrieves the horizontal and vertical scroll position information for the window.
Prototype
wxwindowvar.getscrollpositions (
integer vpositionvrangehpositionhrangeerror
Parameters
| Parameter | Default value | Type name | Description |
|---|---|---|---|
| vposition | .nul | integer | Specifies an object to hold the vertical scroll position. This must be a pre-initialized integer object. |
| vrange | .nul | integer | Specifies an object to hold the range of the vertical scroll bar. This must be a pre-initialized integer object. |
| hposition | .nul | integer | Specifies an object to hold the horizontal scroll position. This must be a pre-initialized integer object. |
| hrange | .nul | integer | Specifies an object to hold the range of the horizontal scroll bar. This must be a pre-initialized integer object. |
| 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 execution 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.
|
setbackgroundrgb()
Description
Sets the background color of the window. The wxwindow 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
wxwindowvar.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 window. 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 window. The wxwindow object itself is returned, to allow multiple setting methods to be put into one expression.
Prototype
wxwindowvar.setcaptiontext (
string captiontext
Parameters
| Parameter | Default value | Type name | Description |
|---|---|---|---|
| captiontext | None | string | The text which is to appear in any caption bar the window has. |
seticon()
Description
Sets the icon for the window. This must be a window that has a caption bar,
otherwise an error is returned in the error
parameter. The wxwindow object itself is returned, to
allow multiple setting methods to be put into one expression.
Prototype
wxwindowvar.seticon (
wxbitmap iconerror
Parameters
| Parameter | Default value | Type name | Description |
|---|---|---|---|
| icon | None | wxbitmap | The wxbitmap that should be used as the window 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 window. The wxwindow object itself is returned, to allow multiple setting methods to be put into one expression.
Prototype
wxwindowvar.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 window either relative to its parent window, if any, or on the screen. |
| top | The current value of the top property | integer | The new position of the top edge of the window either relative to its parent window, if any, or on the screen. |
| outerwidth | The current value of the outerwidth property | integer |
The new width of the entire window, including borders, titles, and other parts
which are not used by window content or child windows. 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 window, including borders, titles, and other
parts which are not used by window content or child windows. 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 window, not including borders,
titles, etc. 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 window, not including
borders, titles, etc. It is an error to specify both
outerheight and innerheight
arguments.
|
setscrollbars()
Description
Sets the visibility of the scroll bars for the window. The wxwindow object itself is returned, to allow multiple setting methods to be put into one expression.
Prototype
wxwindowvar.setscrollbars (
boolean vscrollbarhscrollbar
Parameters
| Parameter | Default value | Type name | Description |
|---|---|---|---|
| vscrollbar | The current value of the vscrollbar property | boolean | Determines whether or not the vertical scroll bar is visible on the screen. |
| hscrollbar | The current value of the hscrollbar property | boolean | Determines whether or not the horizontal scroll bar is visible on the screen. |
setscrollpositions()
Description
Sets the horizontal and/or vertical scroll position of the content of the window.
Prototype
wxwindowvar.setscrollpositions (
integer vpositionhposition
Parameters
| Parameter | Default value | Type name | Description |
|---|---|---|---|
| vposition | Current vertical position | integer | Specifies the vertical position to where the content should be moved. |
| hposition | Current horizontal position | integer | Specifies the horizontal position to where the content should be moved. |
setstate()
Description
Sets the 'state' of the window. The 'state' is considered to be those things which determine the general accessibility of the window. The wxwindow object itself is returned, to allow multiple setting methods to be put into one expression. It is an error to call this method on a child window with values that will try to minimize or maximize it.
Prototype
wxwindowvar.setstate (
boolean visibleminimizedmaximized
Parameters
| Parameter | Default value | Type name | Description |
|---|---|---|---|
| visible | The current value of the visible property | boolean | Determines whether or not the window is visible on the screen. |
| minimized | The current value of the minimized property | boolean |
Determines whether or not the window is to be displayed in a minimized state
(also known as iconized). It is an error for both
minimized and maximized
arguments to be specified as .true. If both
minimized and maximized
arguments are specified as .false then the
window will be restored, or returned to a 'normal' state.
|
| maximized | The current value of the maximized property | boolean |
Determines whether or not the window is to be displayed in a maximized state,
i.e. expanded to cover the whole available display. It is an
error for both minimized and maximized arguments to be specified
as .true. If both minimized
and maximized arguments are specified as
.false then the window will be restored, or
returned to a 'normal' state.
|