Library toolkit_lib: Class FlexComponent

All Classes, All Libraries

Index: A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P | Q | R | S | T | U | V | W | X | Y | Z

This is the base class for the UI components in the toolkit library. This class should not be used by itself. Instead, application writers should use the subclasses of FlexComponent. The common API that all components share for registering listeners, setting and getting the width/height, and drawing to the screen is defined in FlexComponent class.

#include <toolkit/comp.h>

• Class Data and Methods
  • Inherited Data and Methods
• Ancestors
• Descendants
• USAGE
• Descriptions of Class Data and Methods

Class Data and Methods

Back to the top of FlexComponent

Ancestors

Back to the top of FlexComponent

Descendants

• Adjustable
  • FlexScrollbar
• FlexButton
  • FlexMenu
  • FlexMenuButton
• FlexCanvas
• FlexCheckbox
• FlexContainer
  • AppBase
    • ShellAppBase
  • FlexList
  • FlexPanel
    • FlexHorizontalPanel
    • FlexVerticalPanel
  • FlexScrollPane
  • FlexTable
  • FlexWindow
    • FlexDialog
    • FlexFrame
• FlexImage
• FlexInk
• FlexLabel
• FlexTextComponent
  • FlexTextArea
  • FlexTextField

Back to the top of FlexComponent

USAGE

Programs should not directly instantiate any Flex object - instead they should use the UIFactory object to create the flex object that they desire. The UIFactory object is provided by a "specific UI library", which defines the actual implementation, appearance, and behavior of a given Flex object on a device.

The advantage of using the UIFactory to create UI objects is that it allows the specific UI implementation/class definitions to vary from device to device (or to change during development), without requiring changes to application code. The UIFactory will create a platform-specific derived class of the appropriate Flex class, which can be interacted with via the standard Flex API.

Destroying FlexComponents

FlexComponents must be removed from the UI linkage and set not-visible before they are destroyed. If a FlexComponent has children (implying that it is actually a FlexContainer or derived class), the FlexContainer destructor invokes SetVisible(FALSE) on each child and removes it from the linkage before deleting each child. This implies that if you have statically defined Flex objects under a FlexContainer, you should manually remove them before the parent FlexContainer is deleted, as otherwise the FlexContainer will try to invoke "delete" on the statically defined object, yielding a run-time error, memory corruption, or other undesirable result.

The AppBase will invoke DelayedDelete() on all of its children in its AppBase::Exit() handler - this means that all UI that is currently linked under the AppBase (anywhere in the linkage under the appbase, not just a direct child) will be freed when the app exits. Any UI objects that are not hooked into the UI linkage will need to be freed manually by the application programmer.

There are cases where the programmer may want to free a component while in the middle of a component member function (or say, from within a listener member function which was invoked in response to an event on the component). In these cases, instead of directly invoking "delete" on a component, the programmer would use "DelayedDelete()" to free the object, which puts a message on the application's MessageQueue which when dispatched causes the component to be freed.

Note that Listeners and LayoutManagers are *not* automatically freed when a component is destroyed - it is up to the programmer to keep track of her dynamically allocated listeners and layout managers, and ensure that they are destroyed when no longer in use.

Creating Custom Components

If there is a need for a custom user interface component, the application should subclass FlexCanvas to implement the new component. FlexCanvas will provide methods to draw the component as well as handle mouse and/or keyboard events. FlexComponent should not be subclassed for this purpose.

Back to the top of FlexComponent

This type specifies the horizontal size preference for a component. The default value for most components is HSP_USE_PREF_WIDTH. This will cause the component to calculate its own width based on some attribute (like the width of its text label if any).

HSP_NO_PREF_WIDTH

HSP_USE_PREF_WIDTH

Declared as:

enum {
	HSP_NO_PREF_WIDTH,
	HSP_USE_PREF_WIDTH
    } HorizontalSizePreference;

Back to the top of FlexComponent

enum VerticalSizePreference;

This type specifies the vertical size preference for a component. The default value for most components is VSP_USE_PREF_HEIGHT. This will cause the component to calculate its own height based on some attribute (like the height of its text label if any).

VSP_NO_PREF_HEIGHT

VSP_USE_PREF_HEIGHT

Declared as:

enum {
	VSP_NO_PREF_HEIGHT,
	VSP_USE_PREF_HEIGHT
    } VerticalSizePreference;

Back to the top of FlexComponent

FlexComponent(Boolean isVisible );

Constructor for a FlexComponent. This automatically sets up defaults for FlexComponents. By default, components are enabled. Whether they are visible by default is determined by the FlexUI.

Parameters:

in isVisible

If the component is visible or not.

Prototype:

    FlexComponent(Boolean isVisible = TRUE);

Back to the top of FlexComponent

~FlexComponent(void);

Destructor for the FlexComponent. Frees up memory taken by the component.

Prototype:

    virtual ~FlexComponent(void);

Back to the top of FlexComponent

Result AddComponentListener(ComponentListenerInterface& listener);

Add a component listener to the FlexComponent object. The listener must be derived from ComponentListenerInterface in some form.

Parameters:

in listener

A ComponentListenerInterface object that is subclassed to intercept ComponentEvents.

See also: RemoveComponentListener()

Prototype:

    Result AddComponentListener(ComponentListenerInterface& listener);

Back to the top of FlexComponent

Result AddFocusListener(FocusListenerInterface& listener);

Add a focus listener to the FlexComponent object. The listener must be derived from FocusListenerInterface in some form.

Parameters:

in listener

A FocusListenerInterface object that is subclassed to intercept FocusEvents.

See also: RemoveFocusListener()

Prototype:

    Result AddFocusListener(FocusListenerInterface& listener); 

Back to the top of FlexComponent

Result AddKeyListener(KeyListenerInterface& listener);

Add a key listener to the FlexComponent object. The listener must be derived from KeyListenerInterface in some form.

Parameters:

in listener

A KeyListenerInterface object that is subclassed to intercept KeyEvents.

See also: RemoveKeyListener()

Prototype:

    Result AddKeyListener(KeyListenerInterface& listener);

Back to the top of FlexComponent

Result AddMouseListener(MouseListenerInterface& listener);

Add a mouse listener to the FlexComponent object. The listener must be derived from MouseListenerInterface in some form.

Parameters:

in listener

A MouseListenerInterface object that is subclassed to intercept MouseEvents.

See also: RemoveMouseListener()

Prototype:

    Result AddMouseListener(MouseListenerInterface& listener);

Back to the top of FlexComponent

Result AddMouseMotionListener(MouseMotionListenerInterface& listener);

Add a mouse motion listener to the FlexComponent object. The listener must be derived from MouseMotionListenerInterface in some form.

Parameters:

in listener

A MouseMotionListenerInterface object that is subclassed to intercept MouseEvents.

See also: RemoveMouseMotionListener()

Prototype:

    Result AddMouseMotionListener(MouseMotionListenerInterface& listener);

Back to the top of FlexComponent

void AddNotify(void);

Notify a component that it has been added to a container. This should only be called by containers.

See also: RemoveNotify()

Prototype:

    virtual void AddNotify(void);

Back to the top of FlexComponent

Boolean Contains(WinCoord x, WinCoord y);

Given an (x,y) coordinate pair, the method returns TRUE if the point lies inside the bounds of this FlexComponent. The passed in (x,y) coordinate pair is with respect to the FlexComponent's coordinate system.

Parameters:

in x

X position to check.

in y

Y position to check.

See also: Contains()

Prototype:

    Boolean Contains(WinCoord x, WinCoord y);

Back to the top of FlexComponent

Boolean Contains(WinXYPoint& point);

Given a WinXYPoint object, the method returns TRUE if the point lies inside the bounds of this FlexComponent. The passed in (x,y) coordinate pair is with respect to the FlexComponent's coordinate system.

Parameters:

in point

WinXYPoint position to check.

See also: Contains()

Prototype:

    Boolean Contains(WinXYPoint& point);

Back to the top of FlexComponent

void DelayedDelete(void);

DelayedDelete deletes this component by invoking a routine via MessageQueue::QueuedFunctionCall(). There are cases where you want to delete a component while you are in the middle of one of that component's event handlers (for example, you might want to close and free up a FlexDialog when one of the buttons is pressed, so you want to free the dialog from within the button's ActionListener).

DelayedDelete puts a message on the queue to delete the object, so the current method invocation can complete before the deletion occurs.

Prototype:

    void DelayedDelete(void);

Back to the top of FlexComponent

void DoLayout(void);

Tells the component to do its layout. This is mostly meant for containers to handle. Usually called when the FlexComponent is validated.

See also: Validate()

Prototype:

    virtual void DoLayout(void);                             

Back to the top of FlexComponent

Colorant GetBackground(void);

Find out the background color of the FlexComponent. The default is determined by the specific UI.

Return value: Colorant value of the background for this component.

See also: SetBackground(), GetForeground(), SetForeground()

Prototype:

    virtual Colorant GetBackground(void);                    

Back to the top of FlexComponent

WinRectangle GetBounds(void) const;

Get the bounds of this FlexComponent. The bounds are in its parent's coordinate system.

Return value: WinRectangle value containing the bounds of this component.

See also: SetBounds(), SetLocation(), SetSize()

Prototype:

    WinRectangle GetBounds(void) const;

Back to the top of FlexComponent

FlexComponent *GetComponentAt(WinCoord x, WinCoord y, Boolean visibleOnly );

Find the component at the (x,y) coordinate pair inside this component. Meant primarily for FlexContainers.

Determines if this component or one of its immediate child components contains the (x,y) location. If so, the function returns the containing component. This method only looks one level deep. If the (x,y) location is inside a child component that itself has child components, it does not go looking down that child's component tree.

Parameters:

in x

X coordinate to look for child.

in y

Y coordinate to look for child.

in visibleOnly

TRUE: Only return the containing component if it is visible and all of its ancestors are visible. FALSE: Return the component as long as it contains the location. Its visibility does not matter.

See also: GetComponentAt()

Prototype:

    virtual FlexComponent *GetComponentAt(WinCoord  x, 
                                          WinCoord  y, 
                                          Boolean visibleOnly = FALSE); 

Back to the top of FlexComponent

FlexComponent *GetComponentAt(WinXYPoint& point, Boolean visibleOnly );

Find the component at the point inside this component. Meant primarily for FlexContainers.

Determines if this component or one of its immediate child components contains the point. If so, the function returns the containing component. This method only looks one level deep. If the point is inside a child component that itself has child components, it does not go looking down that child's component tree.

Parameters:

in point

Coordinate to look for child.

in visibleOnly

TRUE: Only return the containing component if it is visible and all of its ancestors are visible. FALSE: Return the component as long as it contains the location. Its visibility does not matter.

See also: GetComponentAt()

Prototype:

    FlexComponent *GetComponentAt(WinXYPoint& point, 
                                  Boolean visibleOnly = FALSE); 

Back to the top of FlexComponent

Colorant GetForeground(void);

Get the foreground color of this component. The default is determined by the specific UI.

Return value: Colorant value of the foreground for this component.

See also: SetForeground(), GetBackground(), SetBackground()

Prototype:

    virtual Colorant GetForeground(void);                            

Back to the top of FlexComponent

FlexComponentID GetID(void);

Get the ID number for this FlexComponent. IDs are optional. The default ID for a component is -1.

Return value: ID value of this component.

See also: SetID()

Prototype:

    FlexComponentID GetID(void);

Back to the top of FlexComponent

WinXYPoint GetLocation(void);

Get the upper-left coordinates of this FlexComponent. The coordinates are in relation to its parent object.

Return value: WinXYPoint value that contains the location of this component.

See also: SetLocation(), GetBounds(), SetBounds()

Prototype:

    WinXYPoint GetLocation(void);

Back to the top of FlexComponent

Dimension GetMinimumSize(void);

Get the minimum size to which this FlexComponent can be set. By default the minimum size will be width equals one, height equals one. Component subclasses may redefine what their minimum size should be.

Return value: Dimension value of the minimum height and width for this component.

See also: GetPreferredSize()

Prototype:

    virtual Dimension GetMinimumSize(void);

Back to the top of FlexComponent

FlexContainer *GetParent(void) const;

Get the parent of this FlexComponent. Only FlexContainers and their subclasses can have FlexComponent children.

Return value: A pointer to the FlexContainer that is the parent of this component.

Prototype:

    virtual FlexContainer *GetParent(void) const;

Back to the top of FlexComponent

FlexWindow *GetFlexWindowAncestor(void);

GetFlexWindowAncestor travels up the UI linkage until it reaches a parent that is a FlexWindow, and returns the pointer. This works even if there are intervening parents (FlexContainers) between the component and the FlexWindow.

Return value: pointer to the parent FlexWindow, or NULL if this object does not lie under a FlexWindow

See also: GetParent()

Prototype:

    FlexWindow *GetFlexWindowAncestor(void);

Back to the top of FlexComponent

Dimension GetPreferredSize(void);

Get the size that is preferred by this FlexComponent. By default, FlexComponents will prefer to be (0,0).

Return value: Dimension value that is the preferred size of this component.

See also: GetMinimumSize()

Prototype:

    virtual Dimension GetPreferredSize(void);

Back to the top of FlexComponent

Dimension GetSize(void) const;

Get the size of this FlexComponent.

Return value: Dimension value that contains the size of the object.

See also: SetSize(), SetBounds(), GetBounds(), GetMinimumSize(), GetPreferredSize()

Prototype:

    virtual Dimension GetSize(void) const;

Back to the top of FlexComponent

void GetSizePreference(HorizontalSizePreference &horizontalSizePref, VerticalSizePreference &verticalSizePref);

Get the component's size preferences.

out horizontalSizePref

HorizontalSizePreference value to set.

out verticalSizePref

VerticalSizePreference value to set.

Prototype:

    void GetSizePreference(HorizontalSizePreference &horizontalSizePref,
			   VerticalSizePreference   &verticalSizePref);

Back to the top of FlexComponent

void Invalidate(void);

Invalidate the geometry of this component and all of its UI ancestors up to the AppBase object (unless they are already invalid). A component whose geometry is invalid will not paint itself until validated. When invalidation reaches the AppBase, a delayed geometry validation call is enqueued on that application's thread. The delayed validation may cause components to be resized, repositioned and repainted.

Return value: void

See also: DoLayout(), Validate(), IsGeometryValid()

Prototype:

    virtual void Invalidate(void);

Back to the top of FlexComponent

Boolean IsEnabled(void) const;

Get the enabled state of this FlexComponent. By default, FlexComponents are enabled when created.

Return value: TRUE if the component is enabled.

See also: SetEnabled()

Prototype:

    Boolean IsEnabled(void) const;

Back to the top of FlexComponent

Boolean IsFocusTraversable(void);

Find out if the focus can go to this object. TRUE will mean the object can get focus.

Return value: TRUE if this object can get the focus.

See also: RequestFocus(), TransferFocus()

Prototype:

    virtual Boolean IsFocusTraversable(void);

Back to the top of FlexComponent

Boolean IsShowing(void) const;

Checks to see if the component is fully visible by making sure this FlexComponent is marked visible and all of its parents are marked visible.

Return value: Returns TRUE if this component is showing.

See also: IsVisible(), SetVisible()

Prototype:

    Boolean IsShowing(void) const;

Back to the top of FlexComponent

Boolean IsGeometryValid(void) const;

Check to see if the FlexComponent is valid (needs to be layed out).

Return value: Returns TRUE if geometry is valid.

See also: Validate(), Invalidate()

Prototype:

    Boolean IsGeometryValid(void) const;

Back to the top of FlexComponent

Boolean IsVisible(void) const;

Tests if this FlexComponent is marked visible. Even if it is visible, it may not be onscreen if a parent is not visible.

Return value: Returns TRUE if visible.

See also: SetVisible()

Prototype:

    Boolean IsVisible(void) const;

Back to the top of FlexComponent

void Paint(void);

Handler to Draw the FlexComponent. Assumes the background has been cleared.

See also: Repaint(), Update(), PaintAll()

Prototype:

    virtual void Paint(void);

Back to the top of FlexComponent

void RemoveComponentListener(ComponentListenerInterface& listener);

Remove a component listener that has been added to this FlexComponent. Pass the component listener to be removed.

Parameters:

in listener

The component listener object that was added to this component.

Prototype:

    void RemoveComponentListener(ComponentListenerInterface& listener);

Back to the top of FlexComponent

void RemoveFocusListener(FocusListenerInterface& listener);

Remove a focus listener that has been added to this FlexComponent. Pass the focus listener to be removed.

Parameters:

in listener

The focus listener object that was added to this component.

Prototype:

    void RemoveFocusListener(FocusListenerInterface& listener);

Back to the top of FlexComponent

void RemoveKeyListener(KeyListenerInterface& listener);

Remove a key listener that has been added to this FlexComponent. Pass the key listener to be removed.

Parameters:

in listener

The Key listener object that was added to this component.

Prototype:

    void RemoveKeyListener(KeyListenerInterface& listener);

Back to the top of FlexComponent

void RemoveMouseListener(MouseListenerInterface& listener);

Remove a mouse listener that has been added to this FlexComponent. Pass the mouse listener to be removed.

Parameters:

in listener

The Mouse listener object that was added to this component.

Prototype:

    void RemoveMouseListener(MouseListenerInterface& listener);

Back to the top of FlexComponent

void RemoveMouseMotionListener(MouseMotionListenerInterface& listener);

Remove a mouse motion listener that has been added to this FlexComponent. Pass the mouse motion listener to be removed.

Parameters:

in listener

The MouseMotion listener object that was added to this component.

Prototype:

    void RemoveMouseMotionListener(MouseMotionListenerInterface& listener);

Back to the top of FlexComponent

void RemoveNotify(void);

Notify a component that it has been removed from a container. This should only be called by containers.

See also: AddNotify()

Prototype:

    virtual void RemoveNotify(void);

Back to the top of FlexComponent

void Repaint(void);

Repaint the FlexComponent. This initiates an Update(), which draws in the background, and a Paint(), which draws the FlexComponent.

See also: Paint(), Update()

Prototype:

    virtual void Repaint(void);

Back to the top of FlexComponent

void Repaint(WinCoord x, WinCoord y, uint16 width, uint16 height);

Repaint part of the FlexComponent. This initiates an Update(), which draws in the background, and a Paint(), which draws the FlexComponent.

Parameters:

in x

X value of where to start drawing.

in y

Y value of where to start drawing.

in width

Width of repaint area.

in height

Height of repaint area.

Prototype:

    virtual void Repaint(WinCoord  x, WinCoord  y, 
			 uint16 width, uint16 height);

Back to the top of FlexComponent

void RequestFocus(void);

If this object is FocusTraversable, it will obtain the focus.

See also: IsFocusTraversable()

Prototype:

    void RequestFocus(void);

Back to the top of FlexComponent

Result SetBackground(Colorant color);

Set the background color for this object.

Parameters:

in color

Colorant value to set the background color.

See also: GetBackground()

Prototype:

    virtual Result SetBackground(Colorant color);

Back to the top of FlexComponent

void SetBounds(WinCoord x, WinCoord y, uint16 width, uint16 height);

Set the bounds of this object. This takes the place of two calls, SetLocation() and SetSize().

The maximum for width and height is INT16_MAX. Width and height parameters that are greater than INT16_MAX are constrained to be INT16_MAX.

Parameters:

in x

X value of where the component should be.

in y

Y value of where the component should be.

in width

New width of the component.

in height

New height of the component.

Prototype:

    void SetBounds(WinCoord  x, WinCoord  y, uint16  width, uint16 height);

Back to the top of FlexComponent

void SetBounds(WinRectangle& rect);

Set the bounds of this object. Unlike the previous SetBounds() function, this one takes the bounding rect of the FlexComponent.

Parameters:

in rect

WinRectangle value of the new bounds for this object.

Prototype:

    void SetBounds(WinRectangle& rect);

Back to the top of FlexComponent

void SetEnabled(Boolean enable);

Set if this object is enabled. Setting to TRUE means the object will be enabled.

Changing the enabled state of a component will force a redraw of the component.

Parameters:

in enable

New enabled status for this component.

Prototype:

    virtual void SetEnabled(Boolean enable);

Back to the top of FlexComponent

Result SetForeground(Colorant color);

Set the foreground color for this FlexComponent.

Parameters:

in color

Colorant value of the new color for this component.

See also: GetForeground()

Prototype:

    virtual Result SetForeground(Colorant color);

Back to the top of FlexComponent

void SetID(FlexComponentID id);

Set an optional ID for this FlexComponent. Useful if you want to have a single listener attached to many FlexComponents. An ID enables the listener to identify the sender of an event. The default ID is -1.

Parameters:

in id

New ID value for this component.

Prototype:

    void SetID(FlexComponentID id); 

Back to the top of FlexComponent

void SetLocation(WinCoord x, WinCoord y);

Set the (x,y) location of this component in relation to its parent container.

Parameters:

in x

X value of where to put the component.

in y

Y value of where to put the component.

Prototype:

    void SetLocation(WinCoord  x, WinCoord  y);

Back to the top of FlexComponent

void SetLocation(const WinXYPoint& point);

Set the (x,y) location of this component in relation to its parent container.

Parameters:

in point

WinXYPoint corresponding to the upper-left position of where to put the component.

Prototype:

    void SetLocation(const WinXYPoint& point);

Back to the top of FlexComponent

void SetSize(const Dimension& dimension);

Set the width and height of this FlexComponent. The upper-left location of the FlexComponent does not change. This cannot be used to make a component smaller than the value returned by GetMinimumSize().

Before you make use of this function, make sure you read and understand the concept of "size preference" described in SetSizePreference(). If you try to resize a component and it doesn't work, it probably means that it's using one or both of HSP_USE_PREF_WIDTH and VSP_USE_PREF_HEIGHT.

Parameters:

in dimension

Dimension value of the new size for this component.

Prototype:

    virtual void SetSize(const Dimension&  dimension);

Back to the top of FlexComponent

void SetSize(uint16 width, uint16 height);

Set the width and height of this FlexComponent. The upper-left location of the FlexComponent does not change. This cannot be used to make a component smaller than the value returned by GetMinimumSize().

The maximum for width and height is INT16_MAX. Width and height parameters that are greater than INT16_MAX are constrained to be INT16_MAX.

Before you make use of this function, make sure you read and understand the concept of "size preference" described in SetSizePreference(). If you try to resize a component and it doesn't work, it probably means that it's using one or both of HSP_USE_PREF_WIDTH and VSP_USE_PREF_HEIGHT.

Parameters:

in width

New width for this component.

in height

New height for this component.

Prototype:

    virtual void SetSize(uint16  width, uint16  height);

Back to the top of FlexComponent

void SetSizePreference(HorizontalSizePreference horizontalSizePref, VerticalSizePreference verticalSizePref);

Set the component's size preferences. A size preference tells a component how to size itself. For example:

A button with HSP_NO_PREF_WIDTH and VSP_USE_PREF_HEIGHT. This button would probably calculate its own height based on the font size used for its text label. It would not calculate its own width. The width would be set by calling SetSize().

Most components have HSP_USE_PREF_WIDTH and VSP_USE_PREF_HEIGHT set by default. It's very likely that you will need to change these values before calling SetSize(). The assumption is that most components will size themselves according to some attribute and the "look" parameter passed into the ui factory.

Parameters:

in horizontalSizePref

HorizontalSizePreference value to set.

in verticalSizePref

VerticalSizePreference value to set.

Prototype:

    void SetSizePreference(HorizontalSizePreference horizontalSizePref,
			   VerticalSizePreference   verticalSizePref);

Back to the top of FlexComponent

Result SetVisible(Boolean visible);

Set if the FlexComponent is visible. If the FlexComponent is visible, may still not be showing on the screen because a parent may not be visible.

Parameters:

in visible

New visible state for this component.

See also: IsShowing()

Prototype:

    virtual Result SetVisible(Boolean visible);

Back to the top of FlexComponent

void TransferFocus(void);

Gives the focus to the next appropriate FlexComponent.

See also: IsFocusTraversable()

Prototype:

    void TransferFocus(void);

Back to the top of FlexComponent

void Update(WinCoord x, WinCoord y, uint16 width, uint16 height);

Draw the background color of the FlexComponent to erase it. Update() invokes a Paint() call to redraw the component.

Parameters:

in x

X value of the upper-left point to update.

in y

Y value of the upper-left point to update.

in width

Width of area to invalidate.

in height

Height of area to invalidate.

Prototype:

    virtual void Update(WinCoord x, WinCoord y, uint16 width, uint16 height);

Back to the top of FlexComponent

void Validate(void);

Make sure that the FlexComponent has a valid layout. This member function is usually called on a FlexContainer.

See also: Invalidate(), DoLayout()

Prototype:

    virtual void Validate(void);

Back to the top of FlexComponent

void ProcessActionEvent(ActionEvent& actionEvent);

Process the action events for this component, passing the events to any registered ActionListener objects.

Parameters:

in actionEvent

ActionEvent object to describe the event.

Prototype:

    virtual void ProcessActionEvent(ActionEvent& actionEvent);

Back to the top of FlexComponent

void ProcessComponentEvent(ComponentEvent& componentEvent);

Process the component event for this component, passing the events to any registered ComponentEvent listeners.

Parameters:

in componentEvent

ComponentEvent object to describe the event.

Prototype:

    virtual void ProcessComponentEvent(ComponentEvent& componentEvent);

Back to the top of FlexComponent

void ProcessFocusEvent(FocusEvent& focusEvent);

Process the focus event for this component, passing the events to any registered FocusListener objects.

Parameters:

in focusEvent

FocusEvent object to describe the event.

Prototype:

    virtual void ProcessFocusEvent(FocusEvent& focusEvent);

Back to the top of FlexComponent

void ProcessKeyEvent(KeyEvent& keyEvent);

Process the key events for this component, passing the events to any registered KeyListener objects.

Parameters:

in keyEvent

KeyEvent object to describe the event.

Prototype:

    virtual void ProcessKeyEvent(KeyEvent& keyEvent);

Back to the top of FlexComponent

void ProcessMouseEvent(MouseEvent& mouseEvent);

Process the mouse events for this component, passing the events to any registered MouseListener objects.

The following mouse events are received by this function. The order in which the events are received is as listed below.

MOUSE_PRESSED indicating mouse was pressed on the FlexComponent. MOUSE_CLICKED indicating mouse was pressed and released without being dragged MOUSE_RELEASED indicating mouse was released on the FlexComponent.

If the mouse is not dragged then a MOUSE_CLICKED event is received by this function before the MOUSE_RELEASED event. If the mouse is dragged then a MOUSE_DRAGGED event is received by the ProcessMouseMotionEvent() before a MOUSE_RELEASED event is received by this function. The order of the events then is MOUSE_PRESSED, MOUSE_DRAGGED and MOUSE_RELEASED.

Parameters:

in mouseEvent

MouseEvent object to describe the event.

Prototype:

    virtual void ProcessMouseEvent(MouseEvent& mouseEvent);

Back to the top of FlexComponent

void ProcessMouseMotionEvent(MouseEvent& mouseEvent);

Process the mouse motion events for this component, passing the events to any registered MouseMotionListener objects.

This function receives the MOUSE_DRAGGED event indicating that the mouse was pressed and dragged on the FlexComponent. The order of the mouse events in this case is MOUSE_PRESSED, MOUSE_DRAGGED and MOUSE_RELEASED.

The MOUSE_PRESSED and MOUSE_RELEASED events are received by ProcessMouseEvent() and the MOUSE_DRAGGED event is received by this function.

Parameters:

in mouseEvent

MouseEvent object to describe the event.

Prototype:

    virtual void ProcessMouseMotionEvent(MouseEvent& mouseEvent);

Back to the top of FlexComponent

void *CopyArea(const WinRectangle *bounds) const;

Extracts a portion of the component into a BitmapHeader. The bitmap returned is allocated on the heap and the caller is responsible for deleting it.

The bitmap returned is in the format that most closely matches the native format of the graphics system's sprite format.

The left side in bounds is column 0 in the returned bitmap. If bounds is passed as NULL, then the entire window is copied out. The window must be visible to have a sprite, which holds the window's image.

The bounds passed will be clipped to this component's bounds and the bounds of all its ancestor component.

Parameters:

in bounds

Rectangle bounds of area to copy.

Prototype:

    void *CopyArea(const WinRectangle *bounds) const;

Back to the top of FlexComponent

WinCoord FontMetric( FontMetricInfo info, const TextState& textState ) const;

Return the requested font metric. See the graphics library for valid font metrics.

Parameters:

in info

FontMetric information that is queried.

in textState

TextState to use for the FontMetric information.

See also: StringWidth()

Prototype:

    WinCoord    FontMetric( FontMetricInfo info,
                            const TextState& textState ) const;

Back to the top of FlexComponent

void BrushLine( WinXYPoint p1, WinXYPoint p2, Colorant lineCOlor, WinCoord penWidth );

Brush a line of variable thickness. Pen is centered along line path.

Parameters:

in p1

(x,y) coordinate pair to start line.

in p2

(x,y) coordinate pair to end line.

in lineColor

Colorant value to use.

in penWidth

Pen width to use.

Prototype:

    void BrushLine( WinXYPoint p1, WinXYPoint p2,
		    Colorant lineCOlor, WinCoord penWidth );

Back to the top of FlexComponent

void DrawLine( WinXYPoint p1, WinXYPoint p2, Colorant lineColor );

Draw a one pixel wide line between two inclusive points.

Parameters:

in p1

(x,y) coordinate pair to start line.

in p2

(x,y) coordinate pair to end line.

in lineColor

Colorant value to use.

Prototype:

    void DrawLine( WinXYPoint p1, WinXYPoint p2,
		   Colorant lineColor );

Back to the top of FlexComponent

void DrawHLine( WinCoord xStart, WinCoord xEnd, WinCoord yCoord, Colorant lineColor );

Draws a one pixel wide horizontal line from the start point to X = endX, inclusive.

Parameters:

in xStart

Starting X position of the horizontal line.

in xEnd

Ending X position of the horizontal line.

in yCoord

Y coordinate of the line to be drawn.

in LineColor

Colorant value to use.

Prototype:

    void DrawHLine( WinCoord  xStart,
		    WinCoord  xEnd,
		    WinCoord  yCoord,
		    Colorant  lineColor );

Back to the top of FlexComponent

void DrawVLine( WinCoord xCoord, WinCoord yStart, WinCoord yEnd, Colorant lineColor);

Draw a vertical line given the two Y coordinate endpoints and the X coordinate.

Parameters:

in xCoord

X coordinate of the line to be drawn.

in yStart

Starting Y coordinate of the vertical line.

in yEnd

Ending Y coordinate of the vertical line.

in lineColor

Colorant value to use.

Prototype:

    void DrawVLine( WinCoord  xCoord,
		    WinCoord  yStart,
		    WinCoord  yEnd,
                    Colorant  lineColor);

Back to the top of FlexComponent

void DrawBitmap(const Bitmap& bitmap, WinXYPoint destUpLeft, Colorant color);

Draws a bitmap into the window.

Parameters:

in bitmap

Bitmap to draw

in destUpLeft

Upper left corner for drawing to start in window

in color

Color in which to draw. The default is RGB_BLACK.

Status: Functional

Prototype:

    void DrawBitmap(const Bitmap& bitmap,
                    WinXYPoint destUpLeft, 
                    Colorant color);

Back to the top of FlexComponent

void DrawBitmap(const Bitmap& bitmap, WinXYPoint destUpLeft);

Draws a bitmap into a window.

When drawing bitmaps of color type BCT_ONE_COLOR, the foreground color drawn is RGB_BLACK. To use a different color, call the version of DrawBitmap() that takes a color argument.

Parameters:

in bitmap

Bitmap to draw

in destUpLeft

Upper left corner for drawing to start in window

Status: Functional

Prototype:

    void DrawBitmap(const Bitmap& bitmap, WinXYPoint destUpLeft);

Back to the top of FlexComponent

void DrawPoint( WinCoord xPos, WinCoord yPos, Colorant dotColor );

Plot a single pixel.

Parameters:

in xPos

X coordinate of point to plot.

in yPos

Y coordinate of point to plot.

in dotColor

Colorant value to use.

Prototype:

    void DrawPoint( WinCoord  xPos, WinCoord yPos, Colorant dotColor );

Back to the top of FlexComponent

void DrawPoint( WinXYPoint point, Colorant dotColor );

Plot a single pixel.

Parameters:

in point

(x,y) coordinate to plot the point.

in dotColor

Colorant value to use.

Prototype:

    void DrawPoint( WinXYPoint point, Colorant dotColor );

Back to the top of FlexComponent

void DrawString( const TCHAR string[], TextState& textState );

Draw the specified string using the specified attributes This version assumes a NULL terminated string.

Parameters:

in string

Null terminated TCHAR string.

in textState

TextState to use. DrawString will update TextState._location to the end position of the string.

Prototype:

    void DrawString( const TCHAR  string[], // NULL terminated str
		     TextState&  textState );

Back to the top of FlexComponent

void DrawString( const TCHAR string[], int32 numChars, TextState& textState );

Draw the specified string using the specified attributes. This version takes a length. 0 means no chars displayed.

Parameters:

in string

TCHAR string to draw.

in numChars

Number of characters to draw from the string.

in textState

TextStae to use. DrawString will update TextState._location to the end position of the string.

Prototype:

    void DrawString( const TCHAR  string[],
		     int32 numChars,  // Length
		     TextState&  textState );

Back to the top of FlexComponent

void DrawUIShape( const UIShape srcUIShape, const WinXYPoint& basePoint, Colorant fgColor, int16 parm0 , int16 parm1 , int16 parm2 , int16 parm3 );

Draws the UI Shape into the window. For the area described by the UI Shape, the color is set. Otherwise the window area is not affected.

Parameters:

in srcUIShape

The UIShape object to draw.

in basePoint

Upper-left point to start drawing the shape.

in fgColor

Color to use.

in parm0

Optional parameter to pass to the UIShape.

in parm1

Optional parameter to pass to the UIShape.

in parm2

Optional parameter to pass to the UIShape.

in parm3

Optional parameter to pass to the UIShape.

Prototype:

    void DrawUIShape( const UIShape srcUIShape,
		      const WinXYPoint&  basePoint,
		      Colorant  fgColor,
		      int16  parm0 = 0, int16  parm1 = 0,
		      int16  parm2 = 0, int16  parm3 = 0 );

Back to the top of FlexComponent

void InvertUIShape( const UIShape srcUIShape, const WinXYPoint& basePoint, int16 parm0 , int16 parm1 , int16 parm2 , int16 parm3 );

Inverts the area specified by a UI Shape. Area outside the UI Shape is not affected. This function merely flips the bits of each pixel in the affected area, if the affected area is not black or white, the results might be surprising.

Parameters:

in srcUIShape

The UIShape object to draw.

in basePoint

Upper-left point to start drawing the shape

in fgColor

Color to use.

in parm0

Optional parameter to pass to the UIShape.

in parm1

Optional parameter to pass to the UIShape.

in parm2

Optional parameter to pass to the UIShape.

in parm3

Optional parameter to pass to the UIShape.

Prototype:

    void InvertUIShape( const UIShape srcUIShape,
			const WinXYPoint& basePoint,
			int16  parm0 = 0, int16  parm1 = 0,
			int16  parm2 = 0, int16  parm3 = 0 );

Back to the top of FlexComponent

void FillRect( WinCoord leftCorner, WinCoord topCorner, WinCoord rightCorner, WinCoord bottomCorner, Colorant fillColor );

Fills a rectangle from the upper-left corner to the lower-right corner. Drawing a second rectangle using the same left side as this right side produces NO vertical overlap.

Parameters:

in leftCorner

Upper-left X coordinate of the rectangle.

in topCorner

Upper-left Y coordinate of the rectangle.

in rightCorner

Lower-right X coordinate of the rectangle.

in bottomCorner

Lower-right Y coordinate of the rectangle.

in fillColor

Color to fill the rectangle.

Prototype:

    void FillRect( WinCoord  leftCorner,
		   WinCoord  topCorner,
		   WinCoord  rightCorner,
		   WinCoord  bottomCorner,
		   Colorant  fillColor );

Back to the top of FlexComponent

void InvertRect( WinCoord leftCorner, WinCoord topCorner, WinCoord rightCorner, WinCoord bottomCorner );

Inverts a rectangle in the bitmap. The corners are points, so the lower-right corner pixel is not affected. This function merely flips the bits of each pixel in the affected area, if the affected area is not black or white, the results might be surprising.

Parameters:

in leftCorner

Upper-left X coordinate of the rectangle.

in topCorner

Upper-left Y coordinate of the rectangle.

in rightCorner

Lower-right X coordinate of the rectangle.

in bottomCorner

Lower-right Y coordinate of the rectangle.

Prototype:

    void InvertRect( WinCoord  leftCorner,
		     WinCoord  topCorner,
		     WinCoord  rightCorner,
		     WinCoord  bottomCorner );

Back to the top of FlexComponent

void InvertLine( WinXYPoint p1, WinXYPoint p2 );

Invert a single-pixel wide line. This function merely flips the bits of each pixel in the affected area, if the affected area is not black or white, the results might be surprising.

Parameters:

in p1

(x,y) coordinate pair to start inverted line.

in p2

(x,y) coordinate pair to end inverted line.

Prototype:

    void InvertLine( WinXYPoint p1, WinXYPoint p2 );

Back to the top of FlexComponent

void InvertLine( WinCoord x1, WinCoord y1, WinCoord x2, WinCoord y2 );

Invert a single-pixel wide line. This function merely flips the bits of each pixel in the affected area, if the affected area is not black or white, the results might be surprising.

Parameters:

in x1

X coordinate to start the line.

in y1

Y coordinate to start the line.

in x2

X coordinate to end the line.

in y2

Y coordinate to end the line.

Prototype:

    void InvertLine( WinCoord x1, WinCoord y1,
		     WinCoord x2, WinCoord y2 );

Back to the top of FlexComponent

void SetClipRect( const WinXYPoint& clipUpLeft, const WinXYPoint& clipLowRight );

SetClipRect sets a clipping rect for this object, so that subsequent drawing operations are clipped to the rectangle. If a clip rectangle is already set, this replaces it.

Parameters:

in clipUpLeft

- the upper left coord

in clipLowRight

- the lower right coord

Prototype:

    void	SetClipRect( const WinXYPoint&  clipUpLeft,
			     const WinXYPoint&  clipLowRight );

Back to the top of FlexComponent

void ClearClipRect(void);

ClearClipRect clears out a clip rectangle that was previously set.

See also: SetClipRect()

Prototype:

    void	ClearClipRect(void);

Back to the top of FlexComponent

void Render(Renderer& renderer);

Have the passe renderer draw into this component. The renderer's RenderInto() method is called with this component's window as an argument.

Parameters:

in renderer

A sub-class of Renderer.

Prototype:

    void        Render(Renderer& renderer);

Back to the top of FlexComponent

WinCoord StringWidth( const TCHAR string[], const TextState& textState ) const;

Return the width in window coordinates of the specified string.

Parameters:

in string

A null terminated TCHAR string.

in textState

TextState describing type of text to use.

See also: FontMetric()

Prototype:

    WinCoord    StringWidth( const TCHAR string[], // NULL terminated
                             const TextState& textState ) const;

Back to the top of FlexComponent

WinCoord StringWidth( const TCHAR string[], int32 numChars, const TextState& textState ) const;

Return the width in window coordinates of the specified string.

Parameters:

in string

A TCHAR string.

in numChars

Number of characters to use.

in textState

TextState describing type of text to use.

See also: FontMetric()

Prototype:

    WinCoord    StringWidth( const TCHAR string[],
                             int32 numChars,      // Length
                             const TextState& textState ) const;

Back to the top of FlexComponent

EC (static void EnsureInAppThread(void));

Ensures that the current thread is an application thread

Return value: ASSERTS if not called from the App thread.

Prototype:

    EC (static void EnsureInAppThread(void));

Back to the top of FlexComponent