PtWidget

PtWidget — The parent class of all widgets.

Synopsis

class PtWidget
{
    area;            // PhArea  (Pt_ARG_AREA)    
    border_width;    // unsigned short  (Pt_ARG_BORDER_WIDTH)    
    cursor_color;    // color  (Pt_ARG_CURSOR_COLOR)    
    cursor_type;     // integer  (Pt_ARG_CURSOR_TYPE)    
    dim;             // PhDim  (Pt_ARG_DIM)    
    eflags;          // flag  (Pt_ARG_EFLAGS)    
    flags;           // flag  (Pt_ARG_FLAGS)    
    help_topic;      // string  (Pt_ARG_HELP_TOPIC)    
    pos;             // PhPoint  (Pt_ARG_POS)    
    resize_flags;    // flag  (Pt_ARG_RESIZE_FLAGS)    
    rid;             // region ID  (RID)    
}
		

Derived Classes

PtBasic

Description

This widget is the parent class of all widgets, and contains many commonly-used instance variables. The PtWidget itself is rarely instantiated.

[Note]

For detailed information, please refer to PtWidget in the Photon documentation.

Instance Variables

area

A PhArea instance, specifying the point of origin and dimensions of the widget. The value of this variable should only be changed with the SetArea method (see below).

border_width

A number of pixels specifying the border width. Default is 2, maximum is 15.

cursor_color

A number specifying the color of the pointer when it is inside the widget. Default is 0xffffe0 (cream).

cursor_type

The type of cursor.

This instance variable may have one of the following values:

ConstantDescription
Ph_CURSOR_NO_INHERITDo not inherit the parent's cursor.
Ph_CURSOR_MANUAL_CONTROLNot implemented.
Ph_CURSOR_NONEDo not show a cursor.
Ph_CURSOR_BITMAPNot implemented.
Ph_CURSOR_INHERITInherit the parent's cursor.
Ph_CURSOR_POINTERPointer
Ph_CURSOR_BIG_POINTERBig Pointer
Ph_CURSOR_MOVEMove
Ph_CURSOR_CROSSHAIRCrosshair
Ph_CURSOR_CLOCKClock
Ph_CURSOR_WAITWait
Ph_CURSOR_NOINPUTNo Input
Ph_CURSOR_DONTDon't
Ph_CURSOR_FINGERFinger
Ph_CURSOR_INSERTInsert
Ph_CURSOR_DRAG_VERTICALDrag Vertical
Ph_CURSOR_DRAG_TOPDrag Top
Ph_CURSOR_DRAG_BOTTOMDrag Bottom
Ph_CURSOR_DRAG_HORIZONTALDrag Horizontal
Ph_CURSOR_DRAG_LEFTDrag Left
Ph_CURSOR_DRAG_RIGHTDrag Right
Ph_CURSOR_DRAG_BACKDIAGDrag Backdiag
Ph_CURSOR_DRAG_TLDrag Top Left
Ph_CURSOR_DRAG_BRDrag Bottom Right
Ph_CURSOR_DRAG_FOREDIAGDrag Foreward Diagonal
Ph_CURSOR_DRAG_TRDrag Top Right
Ph_CURSOR_DRAG_BLDrag Bottom Left
Ph_CURSOR_POINT_WAITPoint Wait
Ph_CURSOR_LONG_WAITLong Wait
Ph_CURSOR_QUESTION_POINTQuestion Point
Ph_CURSOR_PASTEPaste

dim

A PhDim instance specifying the widget dimensions. The value of this variable should only be changed with the SetDim method (see below).

eflags

Extended flags common to all widgets.

This instance variable may be a combination of zero or more of the following flags:

ConstantDescription
Pt_CONSUME_EVENTSConsume all events, even if no event handler is defined
Pt_INTERNAL_HELPDisplay the widget's help in a balloon instead of in the Helpviewer
Pt_WIN_REQUESTInternal informational bit
Pt_SKIP_CHILDRENInternal informational bit
Pt_DAMAGE_PARENTPropagate any damage on this widget to its parent
Pt_DAMAGE_ON_FOCUSInternal informational bit

flags

Flags common to all widgets.

This instance variable may be a combination of zero or more of the following flags:

ConstantDescription
Pt_HIGHLIGHTEDDraw a beveled border around the widget.
Pt_AUTOHIGHLIGHTAutomatically display/remove the highlight border as the cursor passes over the widget.
Pt_ETCH_HIGHLIGHTDraw a double bevel if Pt_HIGHLIGHTED is on.
Pt_SETMake the widget 'set'. This will invert the coloring on the bevel as well.
Pt_TOGGLEThe widget's SET flag will toggle on each mouse click instead of changing with mouse down/mouse up events.
Pt_SELECTABLEThe widget may be selected, causing Pt_CB_ARM/ACTIVATE/DISARM events.
Pt_GHOSTThe widget is displayed 'ghosted'. This does not affect its response to events.
Pt_BLOCKEDThe widget will be unresponsive to events.
Pt_REALIZEDThe widget is visible on the display.
Pt_CLIP_HIGHLIGHTThe corners of the highlight rectangle are clipped off.
Pt_OPAQUEMakes the widget opaque within its own extent and for everything behind it.
Pt_DELAY_REALIZEThe widget won't be realized except by a call to PtRealizeWidget().
Pt_GETS_FOCUSThe widget may get the keyboard focus.
Pt_MENU_BUTTONMakes the widget a menu item.
Pt_DESTROYEDMarks the widget for destruction.
Pt_DAMAGEDMarks the widget for repairs.
Pt_OBSCUREDThe widget is covered by another widget, or is outside its parent's canvas.
Pt_IN_FLUXA call to PtContainerHold() has been made on the widget.
Pt_CLEARKeeps the widget's extent clear of any brothers in front of it.
Pt_DAMAGE_FAMILYThe widget and its children will be repaired.
Pt_SELECT_NOREDRAWThe widget will not redraw when it is selected.
Pt_WIDGET_REBUILDThe widget will be rebuilt once all resources have been changed.
Pt_WIDGET_RESIZEThe widget will be resized once all resources have been changed.
Pt_PROCREATEDThe widget is a procreated child of a compound widget.
Pt_ALL_BUTTONSThe widget treats events on any mouse button as a selection.
Pt_FOCUS_RENDERThe widget will attempt to indicate that it has the keyboard focus through some means.
Pt_CALLBACKS_ACTIVECallbacks for this widget will be called due to changes through code, not just due to user interactions.
Pt_MENUABLEThis widget will respond to the menu button with a Pt_CB_MENU event.
Pt_NOREDRAW_SETNoredraw Set
Pt_FREE_MEMORYFrees memory associated with widget pointers.
Pt_REGIONForce the widget to have a region ID.
Pt_REALIZINGThe widget is being realized.

help_topic

A string that contains help information, if the eflags Pt_INTERNAL_HELP flag is set. Otherwise the variable sets the topic position in the HTML help file.

pos

A PhPoint that specifies the position of the upper-left corner of the widget. The value of this variable should only be changed with the SetPos method (see below).

resize_flags

Flags common to all widgets that control their resizability on the x and/or y axis.

This instance variable may be a combination of zero or more of the following flags:

ConstantDescription
Pt_RESIZE_X_INITIALOnly resize the widget in X to contain its children when first created.
Pt_RESIZE_X_AS_REQUIREDResize the widget in X only if its children extend beyond the current X extent
Pt_RESIZE_X_ALWAYSAlways resize the widget to exactly contain its children.
Pt_RESIZE_Y_INITIALOnly resize the widget in X to contain its children when first created.
Pt_RESIZE_Y_AS_REQUIREDResize the widget in Y only if its children extend beyond the current Y extent
Pt_RESIZE_Y_ALWAYSAlways resize the widget to exactly contain its children.

rid

The region ID of the widget, or 0 if the widget has no explicit region. The region can be made explicit using the Pt_REGION flag.

[Warning]

The region ID is read-only. Do not attempt to set this variable to any other value.

Callbacks

The following callbacks are associated with this widget:

CallbackDescription
Pt_CB_BLOCKEDThis callback is generated when a blocked event must be ignored.
Pt_CB_DESTROYEDThis callback is generated when a widget is destroyed.
Pt_CB_HOTKEYThis callback is generated when a key event matches key cap and key modifiers of a common class.
Pt_CB_RAWThis callback is generated when a raw event matches the event mask of a raw callback.
Pt_CB_REALIZEDThis callback is generated when a widget is realized.
Pt_CB_UNREALIZEDThis callback is generated when a widget is unrealized.

Associated Classes

PtHotkeyCallback, PtCallbackInfo

Methods

[Note]

To use any of these methods, you must load the PhotonWidgets.lsp library with a call to require_lisp("PhotonWidgets.lsp").

Setting Position, Dimension, and Area

[Important]

The three methods here are the only reliable way to set or change the dim, pos, and area variables of any widget. Attempting to change these variables or their sub-components without using these methods will lead to unpredictable results in your program.

Syntax

widget.SetPos(x,y)
widget.SetDim(w,h)
widget.SetArea(x,y,w,h)
		

Arguments

xThe integer number of pixels on the x-axis (to the right) to locate the widget, measuring from the upper-left corner of the containing widget.
yThe integer number of pixels on the y-axis (down) to locate the widget, measuring from the upper-left corner of the containing widget.
wThe width of the widget in pixels, expressed as an integer.
hThe height of the widget in pixels, expressed as an integer.

Return

t on success, or nil on failure.

Description

All widget measurements are made in pixels, with respect to the upper-left corner of the widget. The position of a widget is the distance of its upper-left corner from the upper-left corner of its immediate container, on the x and y axes. The dimensions of a widget are always relative to its own upper-left corner. Remember to load the PhotonWidgets.lsp library with a call to require_lisp("PhotonWidgets.lsp") to use these methods.

Example

This example, ex_PtWidgetdotSetArea.g, is included in the product distribution.

#!/usr/cogent/bin/phgamma

/*
This example puts up a window with a pane and a button, with the
relevant positions and dimensions specified.
*/

function print_area (widget)
{
  princ("\nThe area of the ", class_name(widget),
		" widget is: \n", widget.area, "\n");
}

PtInit(nil);
require_lisp("PhotonWidgets.lsp");

win = new(PtWindow);
win.SetDim(300,200);
win.title = "PtWidget.SetArea Example";

pane = new(PtPane);
pane.SetArea(25,25,250,150);
pane.fill_color = PgRGB(240,220,100);

but = new(PtButton);
but.SetPos(90,25);
but.text_string = "Press Here";

PtAttachCallback(but, Pt_CB_ACTIVATE, `print_area(@pane));
PtAttachCallback(but, Pt_CB_ACTIVATE, `print_area(@but));


PtRealizeWidget(win);
PtMainLoop();

Setting, Testing, and Clearing Bits

Syntax

widget.SetBit(ivar,flag)
widget.ClearBit(ivar,flag)
widget.TestBit(ivar,flag)
		

Arguments

ivarThe name of the instance variable whose flag you wish to set, test, or clear.
flagThe flag you wish to set, test, or clear.

Return

t on success, or nil on failure.

Description

These methods set, clear and test individual flags of instance variables for any PtWidget. Don't forget to load the PhotonWidgets.lsp library with a call to require_lisp("PhotonWidgets.lsp") in order to use them.

Example

An example of these methods can be found at the end of the tutorial Set, Test, and Clear Widget Flags in the Programmer's Manual.

Copying Widgets

Syntax

widget.Copy()

Arguments

none 

Returns

A copy of the widget, or an error message.

Description

This method copies any PtWidget, giving it the same parentage and variable values as the original, and putting it the same position. The values of the following variables are not copied:

accel_key
fill_pattern
help_topic
label_balloon
trans_pattern
window_icon

Further, _callbacks and handles selected (neither of which are actually variables) are also not copied.

Remember to load the PhotonWidgets.lsp library with a call to require_lisp("PhotonWidgets.lsp") before using this method.

Example

This example, ex_PtWidgetdotCopy.g, is included in the product distribution.

#!/usr/cogent/bin/phgamma

/*
 * This example puts up a window with two buttons: an
 * original and copy, and prints their definitions.
 */

PtInit(nil);
require_lisp("PhotonWidgets");

win = new(PtWindow);
win.SetDim(200,130);
win.fill_color = PgRGB(200,220,230);

but = new(PtButton);
but.SetArea(50,25,90,30);
but.fill_color = PgRGB(240,220,180);
but.text_string = "Original";

/*
 * Make the copy and print both widget definitions.
 */
but2 = but.Copy();
but2.SetPos(50,70);
but2.text_string = "Copy";

pretty_princ("Original Button: ",but,"\n");
pretty_princ("Copied Button: ",but2,"\n");

PtRealizeWidget(win);
PtMainLoop();

Convenience Functions

Arguments

widgetA PtWidget.

Functions

These functions are extensions of QNX Photon functions. You can refer to the PtWidget function documentation in QNX Helpviewer for more information about them.

PtWidgetCanvas (widget) -- determines the area inside the widget's border.

Returns a PtRect.

PtWidgetExtent (widget) -- determines the area of the widget.

Returns a PtRect.

PtWidgetOffset (widget) -- determines the offset point (calculated using the upper-left corner) of the parent of the widget from its parent.

Returns t.