PtWidget

Gamma/Photon: Using Gamma™ with the Photon microGUIŽ, Version 4.0
Prev |  | Next

# `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.

| 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:

  Constant | Description
  --- | ---
  Ph_CURSOR_NO_INHERIT | Do not inherit the parent's cursor.
  Ph_CURSOR_MANUAL_CONTROL | Not implemented.
  Ph_CURSOR_NONE | Do not show a cursor.
  Ph_CURSOR_BITMAP | Not implemented.
  Ph_CURSOR_INHERIT | Inherit the parent's cursor.
  Ph_CURSOR_POINTER | Pointer
  Ph_CURSOR_BIG_POINTER | Big Pointer
  Ph_CURSOR_MOVE | Move
  Ph_CURSOR_CROSSHAIR | Crosshair
  Ph_CURSOR_CLOCK | Clock
  Ph_CURSOR_WAIT | Wait
  Ph_CURSOR_NOINPUT | No Input
  Ph_CURSOR_DONT | Don't
  Ph_CURSOR_FINGER | Finger
  Ph_CURSOR_INSERT | Insert
  Ph_CURSOR_DRAG_VERTICAL | Drag Vertical
  Ph_CURSOR_DRAG_TOP | Drag Top
  Ph_CURSOR_DRAG_BOTTOM | Drag Bottom
  Ph_CURSOR_DRAG_HORIZONTAL | Drag Horizontal
  Ph_CURSOR_DRAG_LEFT | Drag Left
  Ph_CURSOR_DRAG_RIGHT | Drag Right
  Ph_CURSOR_DRAG_BACKDIAG | Drag Backdiag
  Ph_CURSOR_DRAG_TL | Drag Top Left
  Ph_CURSOR_DRAG_BR | Drag Bottom Right
  Ph_CURSOR_DRAG_FOREDIAG | Drag Foreward Diagonal
  Ph_CURSOR_DRAG_TR | Drag Top Right
  Ph_CURSOR_DRAG_BL | Drag Bottom Left
  Ph_CURSOR_POINT_WAIT | Point Wait
  Ph_CURSOR_LONG_WAIT | Long Wait
  Ph_CURSOR_QUESTION_POINT | Question Point
  Ph_CURSOR_PASTE | Paste

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:

  Constant | Description
  --- | ---
  `Pt_CONSUME_EVENTS` | Consume all events, even if no event handler is defined
  `Pt_INTERNAL_HELP` | Display the widget's help in a balloon instead of in the Helpviewer
  `Pt_WIN_REQUEST` | Internal informational bit
  `Pt_SKIP_CHILDREN` | Internal informational bit
  `Pt_DAMAGE_PARENT` | Propagate any damage on this widget to its parent
  `Pt_DAMAGE_ON_FOCUS` | Internal informational bit

flags

  Flags common to all widgets.

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

  Constant | Description
  --- | ---
  `Pt_HIGHLIGHTED` | Draw a beveled border around the widget.
  `Pt_AUTOHIGHLIGHT` | Automatically display/remove the highlight border as the cursor passes over the widget.
  `Pt_ETCH_HIGHLIGHT` | Draw a double bevel if `Pt_HIGHLIGHTED` is on.
  `Pt_SET` | Make the widget 'set'. This will invert the coloring on the bevel as well.
  `Pt_TOGGLE` | The widget's SET flag will toggle on each mouse click instead of changing with mouse down/mouse up events.
  `Pt_SELECTABLE` | The widget may be selected, causing `Pt_CB_ARM/ACTIVATE/DISARM` events.
  `Pt_GHOST` | The widget is displayed 'ghosted'. This does not affect its response to events.
  `Pt_BLOCKED` | The widget will be unresponsive to events.
  `Pt_REALIZED` | The widget is visible on the display.
  `Pt_CLIP_HIGHLIGHT` | The corners of the highlight rectangle are clipped off.
  `Pt_OPAQUE` | Makes the widget opaque within its own extent and for everything behind it.
  `Pt_DELAY_REALIZE` | The widget won't be realized except by a call to PtRealizeWidget().
  `Pt_GETS_FOCUS` | The widget may get the keyboard focus.
  `Pt_MENU_BUTTON` | Makes the widget a menu item.
  `Pt_DESTROYED` | Marks the widget for destruction.
  `Pt_DAMAGED` | Marks the widget for repairs.
  `Pt_OBSCURED` | The widget is covered by another widget, or is outside its parent's canvas.
  `Pt_IN_FLUX` | A call to PtContainerHold() has been made on the widget.
  `Pt_CLEAR` | Keeps the widget's extent clear of any brothers in front of it.
  `Pt_DAMAGE_FAMILY` | The widget and its children will be repaired.
  `Pt_SELECT_NOREDRAW` | The widget will not redraw when it is selected.
  `Pt_WIDGET_REBUILD` | The widget will be rebuilt once all resources have been changed.
  `Pt_WIDGET_RESIZE` | The widget will be resized once all resources have been changed.
  `Pt_PROCREATED` | The widget is a procreated child of a compound widget.
  `Pt_ALL_BUTTONS` | The widget treats events on any mouse button as a selection.
  `Pt_FOCUS_RENDER` | The widget will attempt to indicate that it has the keyboard focus through some means.
  `Pt_CALLBACKS_ACTIVE` | Callbacks for this widget will be called due to changes through code, not just due to user interactions.
  `Pt_MENUABLE` | This widget will respond to the menu button with a `Pt_CB_MENU` event.
  `Pt_NOREDRAW_SET` | Noredraw Set
  `Pt_FREE_MEMORY` | Frees memory associated with widget pointers.
  `Pt_REGION` | Force the widget to have a region ID.
  `Pt_REALIZING` | The 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:

  Constant | Description
  --- | ---
  `Pt_RESIZE_X_INITIAL` | Only resize the widget in X to contain its children when first created.
  `Pt_RESIZE_X_AS_REQUIRED` | Resize the widget in X only if its children extend beyond the current X extent
  `Pt_RESIZE_X_ALWAYS` | Always resize the widget to exactly contain its children.
  `Pt_RESIZE_Y_INITIAL` | Only resize the widget in X to contain its children when first created.
  `Pt_RESIZE_Y_AS_REQUIRED` | Resize the widget in Y only if its children extend beyond the current Y extent
  `Pt_RESIZE_Y_ALWAYS` | Always 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.

  | 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:

Callback | Description
--- | ---
`Pt_CB_BLOCKED` | This callback is generated when a blocked event must be ignored.
`Pt_CB_DESTROYED` | This callback is generated when a widget is destroyed.
`Pt_CB_HOTKEY` | This callback is generated when a key event matches key cap and key modifiers of a common class.
`Pt_CB_RAW` | This callback is generated when a raw event matches the event mask of a raw callback.
`Pt_CB_REALIZED` | This callback is generated when a widget is realized.
`Pt_CB_UNREALIZED` | This callback is generated when a widget is unrealized.

## Associated Classes

`PtHotkeyCallback`, `PtCallbackInfo`

## Methods

| 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

| 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

`x` | The 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.
`y` | The integer number of pixels on the y-axis (down) to locate the widget, measuring from the upper-left corner of the containing widget.
`w` | The width of the widget in pixels, expressed as an integer.
`h` | The 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 `gamma_ph_`#`_examples_1_QNX4.tgz` file available on the Cogent Web Site.

    #!/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

`ivar` | The name of the instance variable whose flag you wish to set, test, or clear.
`flag` | The 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 `gamma_ph_`#`_examples_1_QNX4.tgz` file available on the Cogent Web Site.

    #!/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

`widget` | A `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.

Prev | Home | Next
`PtUpDown` | Up | `PtWindow`

Copyright 1995-2002 by Cogent Real-Time Systems, Inc.