Main Page | Class Hierarchy | Compound List | File List | Compound Members | File Members | Related Pages

Control Class Reference

Inherited by Button, Canvas, CanvasGL, CheckBox, ComboBox, EditText, Frame, Label, Pane, RadioButton, ScintillaText, and Spinner.

List of all members.


Detailed Description

The base GUI widget class.

Grid Fitting

By default, you are under control of the location of your widgets, although their dimensions are specified by the class itself. Gridfitting is also provided that locates the controls based on their position in a table. You can turn on gridfitting using the grid method and control it with the sticky method. These methods will automatically gridfit the parent. Gridfitting can't modify any client-assigned parameters (assigning to left, top, width, height).

grid takes two or four arguments. col and colspan are the horizontal first cell and number of cells across for the control; row and rowspan are the same vertically. Gridfitting will find the minimum occupiable area for these cells and put the controls within them.

sticky controls the placement of the control within its grid area. For example, the following pseudoimage is built using this code:

with (a = new MyBox (this))
    grid (0, 0);

with (b = new MyBox (this))
    grid (1, 0);

with (c = new MyBox (this))
{
    grid (0, 1, 2, 1);
    sticky ("<");
}

This creates this image:

gridfit_left.gif
If you don't supply the stickiness for c, then it will be left-aligned as above. If you provide a stickiness of "|", meaning horizontal center, we get:

gridfit_center.gif
If you provide a stickiness of ">", meaning right-aligned, we get:

gridfit_right.gif
Finally, if we provide a stickiness of "<>", meaning to cover the full area, we get:

gridfit_full.gif
Vertical stickiness works the same, but using "^" for top-aligned, "v" for bottom-aligned, "-" for vertically centered, and "^v" to cover the full area vertically.


Mouse Methods

These methods relate to the mouse.

enum  Cursor {
  Arrow, Help, Working, Invalid,
  Text, Crosshair, Wait, SizeAll,
  SizeNESW, SizeNWSE, SizeEW, SizeNS
}
 Cursors that can be passed to the cursor method. More...

void captureMouse ()
 Capture the mouse; when captured, onMouseMove, onLButtonDown, onLButtonUp, onMButtonDown, onMButtonUp, onRButtonDown, onRButtonUp are sent to this control regardless of the position of the mouse.

void releaseMouse ()
 Release the mouse from captureMouse.

bit isCaptor ()
 Return whether this control is holding the mouse captive.

bit inClientRegion (int x, int y)
 Return whether this point is within the client region.

void cursor (Cursor value)
 Set a standard cursor to use when the mouse is over this control.


Public Types

enum  MB {
  OK = 1 << 0, AbortRetryIgnore = 1 << 1, OKCancel = 1 << 3, RetryCancel = 1 << 4,
  YesNo = 1 << 5, YesNoCancel = 1 << 6, IconExclamation = 1 << 7, IconWarning = 1 << 8,
  IconInformation = 1 << 9, IconAsterisk = 1 << 10, IconQuestion = 1 << 11, IconStop = 1 << 12,
  IconError = 1 << 13, IconHand = 1 << 14, Default1 = 1 << 15, Default2 = 1 << 16,
  Default3 = 1 << 17, Default4 = 1 << 18
}
 Message box flags, a combination of the sets of fields following. More...


Public Member Functions

 this (Control parent)
 Set the parent and append this to the parent's children list if it is not null.

 ~this ()
 Free data and children.

void close ()
 Close the control.

void paint ()
 Force a painting on this control.

void paintRegion (int left, int top, int right, int bottom)
 Paint an inclusive region of the control.

Color backgroundColor ()
 The background color of this control.

bit visible ()
 Return whether this control is visible.

Control focus ()
 Get the control with keyboard focus, or null if it's not on this application.

Control makeFocus ()
 Set the control with keyboard focus; pass null to set to none; returns previous focus or null.

void clearFocus ()
 Set the keyboard focus to none.

bit isFocus ()
 Get whether this control has the keyboard focus.

void font (Font font)
 Change the text font; passing null results in no effect.

Font font ()
 Get the text font.

void recalculate ()
 Perform size esimate recalculation.

void enabled (bit value)
 Set whether this is active (true) or grayed and inactive (false).

bit enabled ()
 Return whether this is enabled.

Dispatcherbind (char[] code)
 Bind a keypress to a dispatcher for this control.

Dispatcherbind (char[] code, Dispatcher.Method method)
 Bind a method to the dispatcher and return it.

Dispatcherbind (char[] code, Dispatcher.MethodB method)
 Bind a method to the dispatcher and return it.

Dispatcherbind (char[] code, Dispatcher *dispatcher)
 Bind a dispatcher pointer to the dispatcher and return it.

Hierarchy Methods
These methods deal with the hierarchy tree of controls.

Control parent ()
 Return the parent of this control, or null if it's at the top level.

uint childCount ()
 Return the number of children of this control.

void childIterate (void(*func)(Control child))
 Iterate over the children from back-to-front, calling func on each.

Control child (uint index)
 Return a child indexed in the control.

void deleteChildren ()
 Delete all the children of the control.

Control findFrame ()
 Find the frame object that this control exists within or null.

Grid-Fitting
You can optionally locate controls within a grid, similar to HTML tables.

void grid (int col, int row)
 Set grid parameters.

void grid (int col, int row, int colspan, int rowspan)
 Set grid parameters.

void gridAddRow (int col, inout int row)
 Set grid and add one to the inout row parameter.

void gridAddRow (int col, inout int row, int colspan, int rowspan)
 Set grid and add rowspan to the inout row parameter.

int gridRow ()
 Get the grid row.

void sticky (char[] value)
 Set the control's stickiness.

void pad (int x, int y)
 Set padding used to separate this control from its neighbours.

void border (int x, int y)
 Set border used on each side of the control's children to separate the contents from the border.

void gridExtents (out int colmax, out int rowmax)
 Get the grid extents for the children.

void display ()
 Do any necessary gridfitting.

Advanced Placement
These methods poll and place the exact positioning of a control within its parent.

Normally these coordinates are unlocked and can be assigned by grid-fitting; assigning them locks them so that this value is always used.

void left (int value)
 Assignment to this property results in the control being moved and the control being resized; until it is assigned, it is in flux and can be modified by grid-fitting.

int left ()
 The left margin of the control in its parent's client area.

void top (int value)
 Assignment to this property results in the control being moved and the control being resized; until it is assigned, it is in flux and can be modified by grid-fitting.

int top ()
 The top margin of the control in its parent's client area.

void width (int value)
 Assignment to this property results in the control being moved and the control being resized; until it is assigned, it is in flux and can be modified by grid-fitting.

int width ()
 The width of the control in pixels.

int actualWidth ()
 Return the width of the content of the control, before grid-fitting.

void widthFlex ()
 Make the width flexible.

void widthAndHeight (int width, int height)
 Change width and height.

void right (int value)
 Assignment to this property results in the control being moved and the control being resized; until it is assigned, it is in flux and can be modified by grid-fitting.

int right ()
 The right margin of the control in its parent's client area.

void height (int value)
 Assignment to this property results in the control being moved and the control being resized; until it is assigned, it is in flux and can be modified by grid-fitting.

int height ()
 The height of the control in pixels.

void heightFlex ()
 Make the height flexible.

int actualHeight ()
 Return the width of the content of the control, before grid-fitting.

void bottom (int value)
 Assignment to this property results in the control being moved and the control being resized; until it is assigned, it is in flux and can be modified by grid-fitting.

int bottom ()
 The bottom margin of the control in its parent's client area.

void suggestWidthAndHeight (int twidth, int theight)
 Set suggested dimensions.

void suggestWidth (int twidth)
 Set suggested width.

void suggestHeight (int theight)
 Set suggested height.

int visualWidth ()
 Return the width minus the scrollbar if visible.

int visualHeight ()
 Return the height minus the scrollbar if visible.

Horizontal Scrollbar
These methods, along with the #onHScroll event, control the horizontal scrollbar.

void hscroll (bit value)
 Set whether to display a horizontal scrollbar.

void hscrollRange (int min, int max)
 Set the horizontal scrollbar range.

int hscrollRangeMin ()
 Get the horizontal scrollbar minimum point.

int hscrollRangeMax ()
 Get the horizontal scrollbar maximum point.

void hscrollPoint (int position)
 Set the horizontal scrollbar point.

int hscrollPoint ()
 Get the horizontal scrollbar point.

int hscrollPage ()
 Get the units count in a single horizontal scrollbar page.

void hscrollPage (int size)
 Set the units count in a single horizontal scrollbar page.

Vertical Scrollbar
These methods, along with the #onVScroll event, control the vertical scrollbar.

void vscroll (bit value)
 Set whether to display a vertical scrollbar.

bit vscroll ()
 Return whether the vertical scrollbar can be displayed.

void vscrollRangeAndPage (int min, int max, int page)
 Set both the vertical scrollbar range and page.

void vscrollRange (int min, int max)
 Set the vertical scrollbar range.

int vscrollRangeMin ()
 Get the vertical scrollbar minimum point.

int vscrollRangeMax ()
 Get the vertical scrollbar maximum point.

void vscrollPoint (int position)
 Set the vertical scrollbar point.

int vscrollPoint ()
 Get the vertical scrollbar point.

void vscrollPage (int size)
 Set the units count in a single vertical scrollbar page.

int vscrollPage ()
 Get the units count in a single vertical scrollbar page.


Static Public Member Functions

 this ()
 Setup the registry.

void messageBox (char[] title, char[] message)
 Spawn a message box with an Okay button.

char[] messageBoxEx (char[] title, char[] message, MB flags)
 Spawn a message box with a set of flags.

Dispatchertimer (ulong delay)
 Create a timer; the dispatcher will be notified in delay milliseconds.

Dispatchertimer (ulong delay, Dispatcher.Method method)
 Create a timer and add a dispatch to it, then return the dispatcher.

Dispatchertimer (ulong delay, Dispatcher.MethodB method)
 Create a timer and add a dispatch to it, then return the dispatcher.

ulong elapsedTime ()
 Get the number of milliseconds the program has been running.

ulong elapsedMicroTime ()
 Get the number of microseconds the program has been running.

Processor Capabilities
When writing assembly code, it's useful to know not just the processor you're using but also its variant.

These functions return such values.

bit x86_has_mmx ()
 Return whether this is an Intel x86 processor with MMX capability (Pentium Pro/6 and up).

File Listing
This creates a list of search files from a directory; each file has information such as its name, whether it's a directory, and size.

SearchFile[] listPath (char[] path)
 Get the full list of files in a directory.


Public Attributes

BindingList bindings
 The list of bindings attached to this control.

Dispatcher onChar
 Character has been pressed or is repeating.

Dispatcher onHelp
 Help has been requested for this control; if empty, sends it to its parent.

Dispatcher onHScroll
 A horizontal scrollbar action has been requested.

Dispatcher onKeyDown
 Key has been pressed or is repeating.

Dispatcher onKeyUp
 Key has been released.

Dispatcher onLButtonDown
 Left mouse button has been pressed.

Dispatcher onLButtonUp
 Left mouse button has been released.

Dispatcher onLostFocus
 No longer has keyboard focus.

Dispatcher onMButtonDown
 Middle mouse button has been pressed.

Dispatcher onMButtonUp
 Middle mouse button has been released.

Dispatcher onMouseMove
 Posted when the mouse moves.

Dispatcher onMouseWheel
 The mouse wheel has been spun.

Dispatcher onMouseOver
 The mouse has entered the control's region.

Dispatcher onMouseLeave
 The mouse has left the control's region.

Dispatcher onPaint
 Paint the control.

Dispatcher onRButtonDown
 Right mouse button has been pressed.

Dispatcher onRButtonUp
 Right mouse button has been released.

Dispatcher onVScroll
 A vertical scrollbar action has been requested.

Dispatcher onSizeChanged
 The control size has been altered by gridfitting.

DropDispatcher onDrop
 A set of files have been dropped upon the control.


Static Public Attributes

Registry registry
 The registry singleton.

Clipboard clipboard
 The clipboard singleton.

bit periodicGarbageCollection = true
 Whether to perform a full garbage collection on occasion.


Member Enumeration Documentation

enum Control::Cursor
 

Cursors that can be passed to the cursor method.

Here is an image showing good cursors for each value:

cursors.gif
Enumeration values:
Arrow  The standard arrow cursor.
Help  Arrow with a question mark beside it or the normal arrow cursor if unavailable.
Working  Arrow with an hourglass beside it or the hourglass cursor if unavailable.
Invalid  A crossed-out circle or other insignia indicating invalidity.
Text  The "I" beam text editing cursor.
Crosshair  Vertical and horizontal crossed lines, or the normal arrow cursor if unavailable.
Wait  An hourglass.
SizeAll  An arrow pointing in all four cardinal directions (north, south, east, west).
SizeNESW  A double-pointed arrow pointing north-east and south-west.
SizeNWSE  A double-pointed arrow pointing north-west and south-east.
SizeEW  A double-pointed arrow pointing west and east.
SizeNS  A double-pointed arrow pointing north and south.

enum Control::MB
 

Message box flags, a combination of the sets of fields following.

Enumeration values:
OK  OK.
AbortRetryIgnore  Abort, Retry, Ignore.
OKCancel  OK, Cancel.
RetryCancel  Retry, Cancel.
YesNo  Yes, No.
YesNoCancel  Yes, No, Cancel.
IconExclamation  An exclamation-point icon.
IconWarning  A warning icon (may be IconExclamation).
IconInformation  Information icon.
IconAsterisk  Asterisk icon (may be IconInformation).
IconQuestion  Question-mark icon.
IconStop  Stop-sign icon.
IconError  Error icon (may be IconStop).
IconHand  Hand icon (may be IconStop).
Default1  The first button is the default.
Default2  The second button is the default.
Default3  The third button is the default.
Default4  The fourth button is the default.


Member Function Documentation

Dispatcher* Control.bind charcode  []  ) 
 

Bind a keypress to a dispatcher for this control.

code describes the keypress and ends with a key name (such as "Return") and starts with a combination of shift, control, and ctrl, in any case with any separator. For example, "Shift-X", "Shift CONTROL y", and "CtrlZ". Another modifier is "Focus", which prevents the binding from being called if the control isn't the keyboard focus. See Event for the key names.

The dispatcher pointer returned is valid until the next bind method call only. Unless if frames have their own binding for the key, they will pass it to the first sub-control which has a binding, so you don't need to bind to the frame.

Control Control.child uint  index  ) 
 

Return a child indexed in the control.

Out-of-range values are bounds checked. The order of children is from back-to-front.

void Control.cursor Cursor  value  ) 
 

Set a standard cursor to use when the mouse is over this control.

By default it uses the arrow cursor.

void Control.grid int  col,
int  row,
int  colspan,
int  rowspan
 

Set grid parameters.

col and row are the horizontal and vertical location of the control in the table; colspan and rowspan are the number of cells each covers.

void Control.grid int  col,
int  row
 

Set grid parameters.

colspan and rowspan are set to 1.

char [] Control.messageBoxEx chartitle  [],
charmessage  [],
MB  flags
[static]
 

Spawn a message box with a set of flags.

Returns the name of the button that the user pressed.

void Control.sticky charvalue  []  ) 
 

Set the control's stickiness.

This determines where it is places in its region during gridfitting, and is a combination of:

"<" - Stick to left, default, and used if none is given.
">" - Stick to right.
"|" - Center horizontally.
"<" and ">" - Resize width to cover the full region.


"^" - Stick to top, default, and used if none is given.
"v" - Stick to bottom.
"-" - Center vertically.
"^" and "v" - Resize height to cover the full region.

So "<>^v" means to cover the entire region provided.


Member Data Documentation

Dispatcher Control.onChar
 

Character has been pressed or is repeating.

The keyCode, keyRepeat, and keyPrevious fields are filled in.

DropDispatcher Control.onDrop
 

A set of files have been dropped upon the control.

So long as this dispatcher is empty, the control will not accept drops.

The following example creates a file list control that will load files dropped upon it.

            class FileList : Canvas
            {
                void doDrop (char [] [] files)
                {
                    for (int c; c < files.length; c ++)
                        load (files [c]);
                }

                this (Control parent)
                {
                    super (parent);
                    onDrop.add (&doDrop);
                }
            }

Dispatcher Control.onHScroll
 

A horizontal scrollbar action has been requested.

scrollType contains the variety of action; scrollPoint contains the current point of the scrollbar.

Dispatcher Control.onKeyDown
 

Key has been pressed or is repeating.

The keyCode, keyRepeat, and keyPrevious fields are filled in.

Dispatcher Control.onKeyUp
 

Key has been released.

The keyCode, keyRepeat, and keyPrevious fields are filled in.

Dispatcher Control.onMButtonDown
 

Middle mouse button has been pressed.

x, y, and the flag fields are all filled in.

Dispatcher Control.onMButtonUp
 

Middle mouse button has been released.

x, y, and the flag fields are all filled in.

Dispatcher Control.onMouseLeave
 

The mouse has left the control's region.

This is currently supported under Windows 98 and up only.

Dispatcher Control.onMouseOver
 

The mouse has entered the control's region.

x and y are filled in with the relative coordinates of the mouse.

Dispatcher Control.onMouseWheel
 

The mouse wheel has been spun.

x, y, and the flag fields are all filled in, and the wheel field is filled in with the amount the wheel has been spun in number of units; positive for spun away from the user (pushing it forward), negative for spun towards the user (pulling it backward). Note that this is sent to the Frame that is currently the mouse focus, not any of its controls.

Dispatcher Control.onRButtonDown
 

Right mouse button has been pressed.

x, y, and the flag fields are all filled in.

Dispatcher Control.onRButtonUp
 

Right mouse button has been released.

x, y, and the flag fields are all filled in.

Dispatcher Control.onSizeChanged
 

The control size has been altered by gridfitting.

The event's e.x and e.y hold the previous size.

Dispatcher Control.onVScroll
 

A vertical scrollbar action has been requested.

The default is to scroll the control and repaint it. scrollType contains the variety of action. scrollPoint contains the current point of the scrollbar. scrollDest contains one place you could set the scrollbar to in response.


The documentation for this class was generated from the following file:
Generated on Thu Sep 4 13:12:51 2003 for dig by doxygen 1.3.2