Overview
Examples
Screenshots
Comparisons
Applications
Download
Documentation
Tutorials
UppHub
Status & Roadmap
FAQ
Authors & License
Forums
Funding U++
Search on this site













SourceForge.net Logo

SourceForge.net Logo

GitHub Logo

Discord Logo

Ctrl

 

class Ctrl : public Pte<Ctrl

(Derivation from Pte<Ctrl> allows Ctrl to be pointed to by Ptr<Ctrl>

 

This the base class of GUI widgets hierarchy (that is why U++ widgets are also named "Ctrls").

 

 

Public Member List

 

enum PlacementConstants

Constants used in logical coordinates.

CENTER

Center alignment.

LEFT

Left alignment.

RIGHT

Right alignment.

TOP

Equal to LEFT (better name for vertical coordinate).

BOTTOM

Equal to RIGHT (better name for vertical coordinate)

SIZE

Size alignment.

MINSIZE

Value is determined using GetMinSize.

MAXSIZE

Value is determined using GetMaxSize.

STDSIZE

Value is determined using Get

 


 

enum StateReason

Arguments of State virtual method.

FOCUS

Ctrl got/lost focus.

ACTIVATE

Ctrl was activated.

DEACTIVATE

Ctrl was deactivated.

SHOW

Ctrl visibility changed.

ENABLE

Ctrl was enabled/disable.

EDITABLE

Ctrl editable status changed.

OPEN

Ctrl was open (its top-level Ctrl was open on screen).

CLOSE

Ctrl was closed (its top-level Ctrl was closed).

 


 

enum MouseEvents

Constants that make up event argument of MouseEvent and FrameMouseEvent virtual methods. Value is combination of button and action bit fields.

 

Field masks

BUTTON

Mask for button field.

ACTION

Mask for action field.

 

Actions

MOUSEENTER

Mouse entered Ctrl.

MOUSEMOVE

Mouse moved over Ctrl.

MOUSELEAVE

Mouse left Ctrl.

CURSORIMAGE

Cursor image has to be determined (method should respond with image).

MOUSEWHEEL

Mouse wheel rotated.

DOWN

Mouse button was pressed.

UP

Mouse button was released.

DOUBLE

Mouse button was double-clicked.

REPEAT

When mouse button is pressed for a while, U++ imitates keyboard autorepeat sending this message.

Buttons

LEFT

Left button. (This constant is not defined in MouseEvents, instead LEFT from Placements Constants is used).

RIGHT

Left button. (This constant is not defined in MouseEvents, instead LEFT from Placements Constants is used).

Combinations

LEFTDOWN

Left button pressed.

LEFTDOUBLE

Left button double pressed.

LEFTREPEAT

Left button autorepeat.

LEFTUP

Left button released.

RIGHTDOWN

Right button pressed.

RIGHTDOUBLE

Right button double pressed.

RIGHTREPEAT

Right button autorepeat.

RIGHTUP

Right button released.

 


 

enum { NOBACKPAINT, FULLBACKPAINT, TRANSPARENTBACKPAINT, EXCLUDEPAINT }

These constants are parameters of BackPaint method. They determine back-plane drawing style.

NOBACKPAINT

No backpaint is used.

FULLBACKPAINT

Whole area of Ctrl is backpainted.

TRANSPARENTBACKPAINT

Only transparent child Ctrls are backpainted.

EXCLUDEPAINT

Ctrl is not painted. This is special case for specific system related situations (like OLE control painted by regular Windows routine).

 


 

typedef bool (*MouseHook)(Ctrl *ctrl, bool inframe, int event, Point p, int zdelta, dword keyflags)

Type for hooking mouse events across all Ctrls.

 


 

typedef bool (*KeyHook)(Ctrl *ctrl, dword key, int count)

Type for hooking keyboard events across all Ctrls.

 


 

typedef bool (*StateHook)(Ctrl *ctrl, int reason)

Type for hooking state changes across all Ctrls.

 


 

static Logc PosLeft(int pos, int size)

Creates left (or top) aligned logical coordinate (Logc).

pos

Distance between left margin and left margin of parent's view.

size

Size.

Return value

Logical coordinate.

 


 

static Logc PosRight(int pos, int size)

Creates right (or bottom) aligned logical coordinate (Logc).

pos

Distance between right margin and right margin of parent's view.

size

Size.

Return value

Logical coordinate.

 


 

static Logc PosTop(int pos, int size)

Equal to PosLeft(pos, size).

pos

Distance between top margin and top margin of parent's view.

size

Size.

Return value

Logical coordinate.

 


 

static Logc PosBottom(int pos, int size)

Equal to PosRight(pos, size).

pos

Distance between bottom margin and bottom margin of parent's view.

size

Size.

Return value

Logical coordinate.

 


 

static Logc PosSize(int lpos, int rpos)

Creates logical coordinate where distances between margins and parent's view margins are fixed and size of Ctrl is variable (depends of parent's view size).

lpos

Distance between left/top margin and left/top margin of parent's view.

rpos

Distance between right/bottom margin and right/bottom margin of parent's view.

Return value

Logical coordinate.

 


 

static Logc PosCenter(int size, int offset)

Creates centered logical coordinate, where Ctrl is placed in specified distance from center of parent's view.

size

Size.

offset

Offset from center.

Return value

Logical coordinate.

 


 

static Logc PosCenter(int size)

Equal to PosCenter(size, 0).

size

Size.

Return value

Logical coordinate.

 


 

static Vector<Ctrl *> GetTopCtrls()

Returns all opened top-level Ctrls of process. Top-level Ctrls are those without parent (GetParent() == NULL) - TopWindow Ctrls and pop-up Ctrls.

Return value

Vector of all top Ctrls.

 


 

static Vector<Ctrl *> GetTopWindows()

Returns all opened TopWindows (that is, instances of TopWindow class or classes derived from TopWindow) of process. The difference between GetTopWindows and GetTopCtrls is that GetTopCtrls returns pop-ups too.

Return value

Vector of all TopWindows.

 


 

static void CloseTopCtrls()

Closes all top-level Ctrls.

 


 

static void InstallMouseHook(MouseHook hook)

Installs mouse hook - a routine that receives all mouse input of application before it gets processed by Ctrls. You can install more mouse hooks. Mouse hook routine should return true to indicate the end of processing (and event propagation).

hook

Pointer to hook routine.

 


 

static void DeinstallMouseHook(MouseHook hook)

Uninstalls previously installed mouse hook.

hook

Pointer to hook routine.

 


 

static void InstallKeyHook(KeyHook hook)

Installs keyboard hook - a routine that receives all keyboard input of application before it gets processed by Ctrls. You can install more than one keyboard hooks. Keyboard hook routine should return true to indicate the end of processing (and event propagation).

hook

Pointer to hook routine.

 


 

static void DeinstallKeyHook(KeyHook hook)

Uninstalls previously installed keyboard hook.

hook

Pointer to hook routine.

 


 

static void InstallStateHook(StateHook hook)

Installs state hook - a routine that receives all state changes of any Ctrls.

hook

Pointer to hook routine.

 


 

static void DeinstallStateHook(StateHook hook)

Deinstalls previously installed state hook.

hook

Pointer to hook routine.

 


 

virtual void Paint(Draw& draw)

This method is called when Ctrl's view area is about to be repainted.

draw

Target of draw operations.

 


 

virtual void CancelMode()

This method is called by U++ core in situations when internal state of Ctrl that represents ongoing user action is about to be cleared to default. Typical example of such action is state of Button that is pushed by mouse click - if the pushed state is internally recorded in Button, it should by cleared by this method. Examples of situations when this method is called by framework is removing Ctrl from its parent or releasing mouse capture.

 


 

virtual void Activate()

This method is called when Ctrl is top-level and is activated - it or some of its child Ctrls receives keyboard focus (activation usually has other signs as bringing window foreground or changing its caption).

 


 

virtual void Deactivate()

This method is called when Ctrl is top-level and is deactivated - focus has gone outside of Ctrl and its child Ctrls.

 


 

virtual void DeactivateBy(Ctrl *new_focus)

Similar to Deactivate without parameter, but if a widget that caused deactivation by getting a focus is part of the same appliaction, new_focus contains a pointer to it. If deactivation is caused by switching to another application, this parameter is NULL. Both variants of Deactivate are called, the variant with paremeter is called first.

 


 

virtual Image FrameMouseEvent(int event, Point p, int zdelta, dword keyflags)

This method is called when mouse event happens in frame area of Ctrl not containing any child Ctrls. Default implementation does nothing and returns Image::Arrow().

event

Type of event define by MouseEvents enum.

p

Position of mouse cursor in frame coordinates.

zdelta

Mouse wheel rotation delta (if event is MOUSEWHEEL).

keyflags

Combination of key flags for Shift, Ctrl and Alt keys.

Return value

If event is MOUSEIMAGE, method should return Image to be displayed as mouse cursor.

 


 

virtual Image MouseEvent(int event, Point p, int zdelta, dword keyflags)

This method is called when mouse event happens in view area of Ctrl not containing any child Ctrls. Default implementation calls specific mouse event methods based on event parameter.

event

Type of event define by MouseEvents enum.

p

Position of mouse cursor in view coordinates.

zdelta

Mouse wheel rotation delta (if event is MOUSEWHEEL).

keyflags

Combination of key flags for Shift, Ctrl and Alt keys.

Return value

If event is MOUSEIMAGE, method should return Image to be displayed as mouse cursor.

 


 

virtual void MouseEnter(Point p, dword keyflags)

This method is called by default implementation of MouseEvent when mouse cursor enters the view area of Ctrl.

p

Point of mouse cursor in view coordinates.

keyflags

Combination of key flags for Shift, Ctrl and Alt keys.

 


 

virtual void MouseMove(Point p, dword keyflags)

This method is called by default implementation of MouseEvent when mouse cursor hovers above view area of Ctrl.

p

Position of mouse cursor in view coordinates.

keyflags

Combination of key flags for Shift, Ctrl and Alt keys.

 


 

virtual void LeftDown(Point p, dword keyflags)

This method is called by default implementation of MouseEvent when mouse left button is pressed.

p

Position of mouse cursor in view coordinates.

keyflags

Combination of key flags for Shift, Ctrl and Alt keys.

 


 

virtual void LeftDouble(Point p, dword keyflags)

This method is called by default implementation of MouseEvent when mouse left button is double-clicked. Default implementation calls LeftDown.

p

Position of mouse cursor in view coordinates.

keyflags

Combination of key flags for Shift, Ctrl and Alt keys.

 


 

virtual void LeftTriple(Point p, dword keyflags)

This method is called by default implementation of MouseEvent when mouse left button is triple-clicked. Default implementation calls LeftDown.

 


 

virtual void LeftDrag(Point p, dword keyflags)

This method is called by default implementation of MouseEvent when user moves the mouse while holding left button by more than GUI_DragDistance pixels. p is the starting point of drag, not the current mouse position.

 


 

virtual void LeftHold(Point p, dword keyflags)

This method is called by default implementation of MouseEvent when user holds the mouse left button down for a while.

 


 

virtual void LeftRepeat(Point p, dword keyflags)

This method is repeatedly called by default implementation of MouseEvent when mouse left button is pressed for some time, imitating keyboard autorepeat behaviour.

p

Position of mouse cursor in view coordinates.

keyflags

Combination of key flags for Shift, Ctrl and Alt keys.

 


 

virtual void LeftUp(Point p, dword keyflags)

This method is called by default implementation of MouseEvent when mouse left button is released.

p

Position of mouse cursor in view coordinates.

keyflags

Combination of key flags for Shift, Ctrl and Alt keys.

 


 

virtual void RightDown(Point p, dword keyflags)

This method is called by default implementation of MouseEvent when mouse right button is pressed.

p

Position of mouse cursor in view coordinates.

keyflags

Combination of key flags for Shift, Ctrl and Alt keys.

 


 

virtual void RightDouble(Point p, dword keyflags)

This method is called by default implementation of MouseEvent when mouse right button is double-clicked. Default implementation calls RightDown.

p

Position of mouse cursor in view coordinates.

keyflags

Combination of key flags for Shift, Ctrl and Alt keys.

 


 

virtual void RightTriple(Point p, dword keyflags)

This method is called by default implementation of MouseEvent when mouse right button is triple-clicked. Default implementation calls RightDown.

 


 

virtual void RightDrag(Point p, dword keyflags)

This method is called by default implementation of MouseEvent when user moves the mouse while holding right button by more than GUI_DragDistance pixels. p is the starting point of drag, not the current mouse position.

 


 

virtual void RightHold(Point p, dword keyflags)

This method is called by default implementation of MouseEvent when user holds the mouse right button down for a while.

 


 

virtual void RightRepeat(Point p, dword keyflags)

This method is repeatedly called by default implementation of MouseEvent when mouse right button is pressed for some time, imitating keyboard autorepeat behaviour.

p

Position of mouse cursor in view coordinates.

keyflags

Combination of key flags for Shift, Ctrl and Alt keys.

 


 

virtual void RightUp(Point p, dword keyflags)

This method is called by default implementation of MouseEvent when mouse left button is released.

p

Position of mouse cursor in view coordinates.

keyflags

Combination of key flags for Shift, Ctrl and Alt keys.

 


 

virtual void MiddleDown(Point p, dword keyflags)

This method is called by default implementation of MouseEvent when mouse middle button is pressed.

p

Position of mouse cursor in view coordinates.

keyflags

Combination of key flags for Shift, Ctrl and Alt keys.

 


 

virtual void MiddleDouble(Point p, dword keyflags)

This method is called by default implementation of MouseEvent when mouse left button is double-clicked.

p

Position of mouse cursor in view coordinates.

keyflags

Combination of key flags for Shift, Ctrl and Alt keys.

 


 

virtual void MiddleTriple(Point p, dword keyflags)

This method is called by default implementation of MouseEvent when mouse right button is triple-clicked.

p

Position of mouse cursor in view coordinates.

keyflags

Combination of key flags for Shift, Ctrl and Alt keys.

 


 

virtual void MiddleRepeat(Point p, dword keyflags)

This method is repeatedly called by default implementation of MouseEvent when mouse right button is pressed for some time, imitating keyboard autorepeat behaviour.

p

Position of mouse cursor in view coordinates.

keyflags

Combination of key flags for Shift, Ctrl and Alt keys.

 


 

virtual void MiddleDrag(Point p, dword keyflags)

This method is called by default implementation of MouseEvent when user moves the mouse while holding middle button by more than GUI_DragDistance pixels. p is the starting point of drag, not the current mouse position.

 


 

virtual void MiddleHold(Point p, dword keyflags)

This method is called by default implementation of MouseEvent when user holds the mouse middle button down for a while.

p

Position of mouse cursor in view coordinates.

keyflags

Combination of key flags for Shift, Ctrl and Alt keys.

 


 

virtual void MiddleUp(Point p, dword keyflags)

This method is called by default implementation of MouseEvent when mouse middle button is released.

p

Position of mouse cursor in view coordinates.

keyflags

Combination of key flags for Shift, Ctrl and Alt keys.

 


 

virtual void MouseWheel(Point p, int zdelta, dword keyflags)

This method is called by default implementation of MouseEvent when mouse wheel is rotated. Default implementation of this method propagates event to the parent and suppresses call of ChildMouseEvent for the parent.

p

Position of mouse cursor in view coordinates.

zdelta

Amount of rotation.

keyflags

Combination of key flags for Shift, Ctrl and Alt keys.

 


 

virtual void MouseLeave()

This method is called by default implementation of MouseEvent when mouse cursor leaves view area of Ctrl.

 


 

Point GetPreedit()

If the widget is supposed to support text input, it should return top-left corner of insertion point so that host input method can eventually display a composition window near the insertion point with U++ displaying composition text over the spot. Should return Null if widget does not require the text input. Default implementation returns the position of caret.

 


 

Font GetPreeditFont()

Should return the font that is supposed to be used for composition text. Default implementation returns StdFont().

 


 

virtual void DragAndDrop(Point p, PasteClip& d)

This method is called when user performs drag and drop operation over view area. The drag operation can either be just moving the mouse, or actual drop - the difference is that for actual drop the PasteClip::Accept method returns true. This allows to share drag and drop logic, which is very similar, in the single method.

 


 

virtual void FrameDragAndDrop(Point p, PasteClip& d)

This method is called when user performs drag and drop operation over frame area. The drag operation can either be just moving the mouse, or actual drop - the difference is that for actual drop the PasteClip::Accept method returns true. This allows to share drag and drop logic, which is very similar, in the single method.

 


 

virtual void DragRepeat(Point p)

This method is called when user holds his drag operation over single position for some time. This is similar to LeftRepeat and it is usually used to scroll the content of view when DragRepeat occurs at the border area of view.

 


 

virtual void DragEnter()

Called when user enters view with drag.

 


 

virtual void DragLeave()

Called when user's drag leaves the view.

 


 

virtual String GetDropData(const String& fmtconst

This method is invoked to obtain drop data from Ctrl if such data was not supplied as ClipData in call to DoDragAndDrop. Default implementation calls GetSelectionData.

 


 

virtual String GetSelectionData(const String& fmtconst

This method should return the widget's actual selection in requested format. It is used for X11 middle mouse selection paste operation ans as default implementation of GetDropData, because usually the data to be transfered by drag&drop operation is the selection.

 


 

virtual Image CursorImage(Point p, dword keyflags)

This method is called by default implementation of MouseEvent when the shape of mouse cursor is to be determined..

p

Position of mouse cursor in view coordinates.

keyflags

Combination of key flags for Shift, Ctrl and Alt keys.

Return value

Image of new cursor. Default implementation returns Image::Arrow().

 


 

virtual bool Key(dword key, int count)

This method provides keyboard input. When keyboard event occurs and some of U++ application Ctrls has input focus, its Key method is called. If Key method returns true, processing of key event is finished. If it returns false, U++ calls Key method of parent Ctrl and it repeats until either true is returned or Ctrl has no parent. If such top-level Ctrl is reached, U++ calls its HotKey method. Default implementation is void and returns false.

key

Key identifier. If it is less than 65536, it indicates character code, otherwise it is key-code. Key-code is combination of basic key codes and further flags indicating state of shift keys and push/release events.

count

Accumulated autorepeat count.

Return value

Method should return true if further propagation is not desirable (in most cases this indicates that Ctrl accepted the key).

 


 

virtual bool HotKey(dword key)

This method is called when no Ctrl accepts key event using Key method. Default implementation calls HotKey method child Ctrls. If some child Ctrl returns true, method returns true, otherwise it returns false.

key

Key indentifier.

Return value

Method should return true to stop further distribution of key event via HotKey methods.

 


 

virtual void GotFocus()

This method is called when Ctrl receives input focus. Default implementation is void.

 


 

virtual void LostFocus()

This method is called when Ctrl loses input focus. Default implementation is void.

 


 

virtual void ChildFrameMouseEvent(Ctrl *child, int event, Point p, int zdelta, dword keyflags)

This method is invoked before the frame mouse event is routed to the child. Parameters of the event are the same as those in MouseEvent method. Default implementation calls the parent's ChildMouseEvent method.

 


 

virtual void ChildMouseEvent(Ctrl *child, int event, Point p, int zdelta, dword keyflags)

This method is invoked before the mouse event is routed to the child. Parameters of the event are the same as those in MouseEvent method. Default implementation calls the parent's ChildMouseEvent method.

 


 

virtual void ChildGotFocus()

This method is invoked when any of child Ctrls receives input focus.

 


 

virtual void ChildLostFocus()

This method is invoked when any of child Ctrls loses input focus.

 


 

virtual dword GetAccessKeys() const

Ctrl should use this method to signal presence of access keys. Access keys are keyboard keys that can be used to access or activate dialog functions when pressed together with Alt key. They can be defined by application designer (usually using & or \b in labels), or they are automatically synthesized using AssignAccessKeys method. If Ctrl (of one of Ctrls in its child tree) has some access keys and those keys are letters (in range 'A' - 'Z'), they should be returned as bit value using AccessKeyBit function. Other access keys should be indicated by bit 0 (that means, by binary or of 1 to result). Default implementation returns 0.

Return value

Bit set of access keys.

 


 

virtual void AssignAccessKeys(dword used)

This method gives a Ctrl chance to synthesize its letter access keys.

used

Set of letter access keys that are already used and should not be chosen by Ctrl as its access keys.

 


 

virtual void ChildAdded(Ctrl *child)

This method is invoked when child is added to Ctrl.

child

Pointer to child added.

 


 

virtual void ChildRemoved(Ctrl *child)

This method is invoked when child is removed from Ctrl.

child

Pointer to child removed.

 


 

virtual void ParentChange()

This method is called when Ctrl is added or removed from parent.

 


 

virtual void State(int reason)

This method is used to notify Ctrls about special state-change events that are not covered by virtual methods. Method is called for entire child tree of Ctrl whose state has changed.

reason

Code of event. Standard reasons are enumerated by StateReason enum.

 


 

virtual void Layout()

This method is invoked when layout of Ctrl has to be refreshed. This is usually either before window is displayed or when the Ctrl is resized.

 


 

virtual Size GetMinSize() const

This method should return minimal size of Ctrl. This is used e.g. to limit the minimal size of windows. Default implementation returns size suitable for edit-field type of widget, based on default GUI font and EditFieldIsThin setting.

 


 

virtual Size GetStdSize() const

This method should return standard size of Ctrl. Default implementation returns calls GetMinSize, increases width 10 and returns resulting Size.

 


 

virtual Size GetMaxSize() const

This method should return maximal size of Ctrl. Default implementation returns the size of virtual working area. Redefinition can be used to e.g. define the maximum size of window (as maximal size of view area).

 


 

virtual bool IsShowEnabled() const

This method indicates whether Ctrl should be painted as enabled. Default implementation returns IsEnabled() && (!parent || parent->IsShowEnabled()), however TopWindow overloads this function so that owner of modal dialogs while being disabled during modal dialog lifetime are displayed with enabled Ctrls.

Return value

true if Ctrl should be painted as enabled.

 


 

virtual Rect GetOpaqueRect() const

Returns the rectangle of view area that is opaque (is completely filled when painting the widget). The default implementation returns the whole view area if Transparent flag is set, empty rectangle otherwise. Paint routine uses this information to optimize.

 


 

virtual Rect GetVoidRect() const

Returns the rectangle of view area that is fully transparent (nothing is painted in that rectangle). Paint routine uses this information to optimize.

 


 

virtual void Updated()

Invoked by Update method. Default implementation is empty.

 


 

virtual int OverPaint() const

This method can returns non-zero number that represents paint extension margin of view area - Ctrl can paint inside this margin despite that fact that it does not belong to view. This is useful to represent some specific skinning effect (like glare around the button). Default implementation returns zero.

 


 

virtual void Close()

Closes top-level Ctrl. If Ctrl is not top-level, has no effect. If it is and is open in host GUI (either as pop-up or as TopWindow), it should close it. Default implementation closes. TopWindow overrides this method to break modal loop instead of closing if modal loop is performed for it.

 


 

virtual bool IsOcxChild()

Used for Ocx control implementation.

 


 

virtual String GetDesc() const

Returns description of Ctrl for diagnostic purposes. Default implementation is empty.

 


 

Callback WhenAction

This callback is used to signal that user has changed the value (or state) of widget.

 


 

virtual void SetData(const Value& data)

Sets the new value to the object. Default implementation is void.

 


 

virtual Value GetData() const

Gets current value of the object. Default implementation returns Value() - void value.

Return value

Value of object.

 


 

virtual void SetModify()

Sets modification flag.

 


 

virtual void ClearModify()

Clears modification flag.

 


 

virtual bool IsModified() const

Returns the value modification flag.

 


 

virtual bool Accept()

This virtual method is called when value of Ctrl is about to be accepted. Default implementation calls Accept for all child Ctrls and returns false if any of child Ctrls returns false, true otherwise.

Typical use is when user pressed OK button. If any Ctrl of dialog returns false, OK is canceled.

Typical implementation of this method should test whether current state of Ctrl (its edited value) matches requirements. If it does, it should finish editing, accept edited value and return true. Otherwise it should return false,

Return value

Ctrl should return true if it successfully finished editing, false otherwise.

 


 

virtual void Reject()

This virtual method is called when Ctrl should abort editing, discarding edited value. Default implementation calls Reject for all child Ctrls.

 


 

virtual void Serialize(Stream& s)

Serialization method. Should serialize the value of Ctrl in a way that is suitable for dialog backup and optional restore (e.g. when user presses Cancel button).

 


 

virtual void Jsonize(JsonIO& jio)

Method to convert the data of widget to/from JSON. Default implementation calls Jsonize for Value obtained/set by GetData/SetData.

 


 

virtual void Xmlize(XmlIO& xio)

Method to convert the data of widget to/from XML. Default implementation calls Jsonize for Value obtained/set by GetData/SetData.

 


 

void AddChild(Ctrl *child)

Adds a child Ctrl as last one.

child

Pointer to child Ctrl at the end of child list. Note that U++ never takes ownership of Ctrls - never calls delete for child. That allows using non-heap based Ctrls.

 


 

void AddChild(Ctrl *child, Ctrl *insafter)

Inserts child Ctrl after another Ctrl that is already child. If insafter is NULL, child is inserted as the first child.

child

Pointer to child Ctrl.

insafter

Ctrl that will be before inserted Ctrl.

 


 

void AddChildBefore(Ctrl *child, Ctrl *insbefore)

Inserts child Ctrl before another Ctrl that is already child. If insbefore, child is inserted as last child.

child

Pointer to child Ctrl.

insbefore

Ctrl that will be after inserted Ctrl.

 


 

void RemoveChild(Ctrl *child)

Removes Ctrl from child list. Ctrl is never deleted.

child

Child to be removed.

 


 

Ctrl *GetParent() const

Returns parent of Ctrl or NULL if Ctrl is topmost.

Return value

Pointer to parent Ctrl.

 


 

Ctrl *GetLastChild() const

Returns last child.

Return value

Pointer to last child or NULL if Ctrl has no children.

 


 

Ctrl *GetFirstChild() const

Returns first child.

Return value

Pointer to first child or NULL if Ctrl has no children.

 


 

Ctrl *GetPrev() const

Returns child that is before this Ctrl in child list or NULL if Ctrl is first or not in list.

Return value

Pointer to previous child or NULL.

 


 

Ctrl *GetNext() const

Returns next child that is after this Ctrl in child list or NULL if Ctrl is last or not in list.

Return value

Pointer to next child or NULL.

 

 


 

int GetChildIndex(const Ctrl *childconst

Returns the index of child (first child has index 0, second child 1 etc...). If child is not present in this Ctrl, returns -1. Note that this function performs sequential scan of child (results in O(n) complexity).

 


 

int GetChildCount() const

Returns the number of child ctrls. Note that this function performs sequential scan of child (results in O(n) complexity).

 


 

template <class TT *GetAscendant() const

Returns first ascendant (parent, parent of parent etc..) that has type T.

 


 

Ctrl *GetIndexChild(int iconst

Retruns child at index i or NULL if there is none. Note that this function performs sequential scan of child (results in O(n) complexity).

 


 

int GetViewChildIndex(const Ctrl *childconst

Returns the index of view child (first child has index 0, second child 1 etc...). If child is not present in this Ctrl or is in frame, returns -1. Note that this function performs sequential scan of child (results in O(n) complexity). This is similar to GetChildIndex, but frame widgets are ignored.

 


 

int GetViewChildCount() const

Returns the number of child ctrls. Note that this function performs sequential scan of child (results in O(n) complexity). This is similar to GetChildCount, but frame widgets are ignored.

 


 

Ctrl *GetViewIndexChild(int iiconst

Retruns view child at index i or NULL if there is none. Note that this function performs sequential scan of child (results in O(n) complexity). This is similar to GetIndexChild, but frame widgets are ignored.

 


 

bool IsChild() const

Return value

True if Ctrl has parent.

 


 

Ctrl *ChildFromPoint(Point& ptconst

Checks whether opened top-level Ctrl is foreground.

Return value

True if Ctrl is foreground.

 


 

bool IsForeground() const

Returns true if Ctrl or its top-level parent is foreground window.

 


 

void SetForeground()

Asks platform to put top-level Ctrl to foreground.

 


 

const Ctrl *GetTopCtrl() const

Gets the top-level Ctrl, that is Ctrl that has this Ctrl in child tree and has no parent.

Return value

Pointer to top-level Ctrl. Can return this.

 


 

Ctrl *GetTopCtrl()

Gets the top-level Ctrl, that is Ctrl that has this Ctrl in child tree and has no parent.

Return value

Pointer to top-level Ctrl. Can return this.

 


 

const Ctrl *GetOwner() const

Returns owner of top-level Ctrl. Example of owned window is dialog launched from main application window. Owner is another top-level Ctrl.

Return value

Pointer to owner top-level Ctrl or NULL is window is not owned.

 


 

Ctrl *GetOwner()

Returns owner of top-level Ctrl.

Return value

Pointer to owner top-level Ctrl or NULL is window is not owned.

 


 

const Ctrl *GetTopCtrlOwner() const

Equivalent to GetTopCtrl()->GetOwner() call.

Return value

Pointer to owner of top-level Ctrl.

 


 

Ctrl *GetTopCtrlOwner()

Equivalent to GetTopCtrl()->GetOwner() call.

Return value

Pointer to owner of top-level Ctrl.

 


 

Ctrl *GetOwnerCtrl()

const Ctrl *GetOwnerCtrl() const

Returns the owner Ctrl. Unlike GetOwner, it returns actual widget that was used as "owner" parameter in Open or PopUp calls.

 


 

const TopWindow *GetTopWindow() const

TopWindow that contains this Ctrl.

Return value

Pointer to TopWindow.

 


 

TopWindow *GetTopWindow()

TopWindow that contains this Ctrl.

Return value

Pointer to TopWindow.

 


 

const TopWindow *GetMainWindow() const

Returns main window (one with no owner) that directly or indirectly owns this Ctrl.

Return value

Pointer to main window.

 


 

TopWindow *GetMainWindow()

Returns main window (one with no owner) that directly or indirectly owns this Ctrl.

Return value

Pointer to main window.

 


 

Ctrl& SetFrame(int i, CtrlFrame& frm)

Sets Frame at given position. If there is no such position yet, required number of NullFrame frames is added. Only reference to frame is stored, that means that frame must exists during the time it is used in Ctrl. Also, some frames can also be used for multiple Ctrls.

i

Position. First frame with i == 0 is outermost.

frm

Reference to frame.

Return value

Returns *this to allow chaining of method calls.

 


 

Ctrl& SetFrame(CtrlFrame& frm)

Sets frame at position 0.

frm

Reference to frame.

Return value

*this.

 


 

Ctrl& AddFrame(CtrlFrame& frm)

Adds frame at inner-most position.

frm

Reference to frame.

Return value

*this.

 


 

const CtrlFrame& GetFrame(int i = 0const

Returns reference to frame at given position.

i

Position.

Return value

Reference to frame.

 


 

CtrlFrame& GetFrame(int i = 0)

Returns reference to frame at given position.

i

Position.

Return value

Reference to frame.

 


 

void RemoveFrame(int i)

Removes frame at given position.

i

Index of frame.

 


 

void RemoveFrame(CtrlFrame& frm)

Removes first frame equal to frm. Equality means here that pointers to both frames are the same (it is same instance).

frm

Frame to remove.

 


 

void InsertFrame(int i, CtrlFrame& frm)

Inserts frame at given position.

i

Position.

frm

Reference to frame.

 


 

int FindFrame(CtrlFrame& frm)

Finds first frame equal to frm. Equality means here that pointers to both frames are the same (it is same instance).

frm

Frame to find.

Return value

Index of frame or negative value if frame is not found.

 


 

int GetFrameCount() const

Returns count of frames in Ctrl.

Return value

Count of frames.

 


 

void ClearFrames()

Removes all frames from Ctrl. Frame at position 0 then added and set to NullFrame.

 


 

bool IsOpen() const

Checks whether top-level Ctrl of this Ctrl is open.

Return value

true if open.

 


 

void Shutdown()

Sets internal flag indicating that Ctrl is being destructed. This is rarely used to solve some destruction order problems.

 


 

bool IsShutdown() const

Checks whether internal shutdown flag is set.

Return value

True if in shutdown mode.

 


 

Ctrl& SetPos(LogPos p, bool inframe)

Sets logical position of Ctrl. If Ctrl is top-level, logical position must be of left-top type.

p

Logical position.

inframe

If true, Ctrl is placed into frame area instead of view area

Return value

*this.

 


 

Ctrl& SetPos(LogPos p)

Sets logical position of Ctrl in view area.

p

Logical position.

Return value

*this.

 


 

Ctrl& SetPos(Logc x, Logc y)

Sets logical position by individual coordinates (in view area).

x

Horizontal logical position.

y

Vertical logical postion.

Return value

*this.

 


 

Ctrl& SetPosX(Logc x)

Sets horizontal logical position only (in view area).

x

Horizontal logical position.

Return value

*this.

 


 

Ctrl& SetPosY(Logc y)

Sets vertical logical position only (in view area).

y

Vertical logical position.

Return value

*this.

 


 

void SetRect(const Rect& r)

Sets left-top logical position (in view area).

r

Rectangle determines left-top position.

 


 

void SetRect(int x, int y, int cx, int cy)

Sets left-top logical position (in view area).

x

Distance between parent rectangle left-edge and Ctrl.

y

Distance between parent rectangle top-edge and Ctrl.

cx

Horizontal size.

cy

Vertical size.

 


 

void SetRectX(int x, int cx)

Sets left horizontal logical position (in view area).

x

Distance between parent rectangle left-edge and Ctrl.

cx

Horizontal size.

 


 

void SetRectY(int y, int cy)

Sets top vertical logical position (in view area).

y

Distance between parent rectangle top-edge and Ctrl.

cy

Vertical size.

 


 

Ctrl& SetFramePos(LogPos p)

Sets logical position of Ctrl in frame area.

p

Logical position.

Return value

*this.

 


 

Ctrl& SetFramePos(Logc x, Logc y)

Sets logical position by individual coordinates (in frame area).

x

Horizontal logical position.

y

Vertical logical postion.

Return value

*this.

 


 

Ctrl& SetFramePosX(Logc x)

Sets horizontal logical position only (in frame area).

x

Horizontal logical position.

Return value

*this.

 


 

Ctrl& SetFramePosY(Logc y)

Sets vertical logical position only (in frame area).

y

Vertical logical position.

Return value

*this.

 


 

void SetFrameRect(const Rect& r)

Sets left-top logical position (in frame area).

r

Rectangle determines left-top position.

 


 

void SetFrameRect(int x, int y, int cx, int cy)

Sets left-top logical position (in frame area).

x

Distance between parent rectangle left-edge and Ctrl.

y

Distance between parent rectangle top-edge and Ctrl.

cx

Horizontal size.

cy

Vertical size.

 


 

void SetFrameRectX(int x, int cx)

Sets left horizontal logical position (in frame area).

x

Distance between parent rectangle left-edge and Ctrl.

cx

Horizontal size.

 


 

void SetFrameRectY(int y, int cy)

Sets top vertical logical position (in frame area).

y

Distance between parent rectangle top-edge and Ctrl.

cy

Vertical size.

 


 

bool InFrame() const

Return value

true when Ctrl has position in frame area.

 


 

bool InView() const

Return value

true when Ctrl has position in view area.

 


 

LogPos GetPos() const

Return value

Logical position of Ctrl

 


 

void RefreshLayout()

Recomputes layout for Ctrl. This includes calling FrameLayout for all frames and calling Layout virtual method. Layout of child widgets is recomputed if their size changes.

 


 

void RefreshLayoutDeep()

Recomputes layout for the whole Ctrl tree - unlike RefreshLayout, recomputes layout of all descendants regardless whether their size has changed.

 


 

void RefreshParentLayout()

If Ctrl has parent, calls parent->RefreshLayout().

 


 

void UpdateLayout()

Recomputes layout of widget by recalculating its frame coverage, then, if view size has changed, calls Layout method (this is the difference from RefreshLayout, which calls Layout always). Layout of child widgets is recomputed if their size changes.

 


 

void UpdateParentLayout()

Calls UpdateLayout for parent (if exists).

 


 

Ctrl& LeftPos(int a, int size = STDSIZE)

Sets left horizontal position (in view area).

a

Distance from left border of parent.

size

Horizontal size.

Return value

*this for method chaining.

 


 

Ctrl& RightPos(int a, int size = STDSIZE)

Sets right horizontal position (in view area).

a

Distance from the right border of parent.

size

Horizontal size.

Return value

*this for method chaining.

 


 

Ctrl& TopPos(int a, int size = STDSIZE)

Sets top vertical position (in view area).

a

Distance from the top border of parent.

size

Vertical size.

Return value

*this for method chaining.

 


 

Ctrl& BottomPos(int a, int size = STDSIZE)

Sets bottom vertical position (in view area).

a

Distance from the bottom border of parent.

size

Vertical size.

Return value

*this for method chaining.

 


 

Ctrl& HSizePos(int a = 0, int b = 0)

Sets horizontal sizing position (in view area).

a

Distance from left border of parent.

b

Distance from right border of parent.

Return value

*this for method chaining.

 


 

Ctrl& VSizePos(int a = 0, int b = 0)

Sets vertical sizing position (in view area).

a

Distance form top border of parent.

b

Distance from bottom border of parent.

Return value

*this for method chaining.

 


 

Ctrl& SizePos()

Same as VSizePos().HSizePos().

Return value

*this for method chaining.

 


 

Ctrl& HCenterPos(int size = STDSIZE, int delta = 0)

Horizontal centered position (in view area).

size

Horizontal size.

delta

Offset from centered position (rarely used).

Return value

*this for method chaining.

 


 

Ctrl& VCenterPos(int size = STDSIZE, int delta = 0)

Vertical centered position (in view area).

size

Vertical size.

delta

Offset from centered position (rarely used).

Return value

*this for method chaining.

 


 

Ctrl& LeftPosZ(int a, int size = STDSIZE)

Sets left horizontal zoomed position (in view area). Distances are recalculated using zoom factor to accommodate size differences between standard font used during layout design and actual standard font.

a

Distance from the left border of parent.

size

Horizontal size.

Return value

*this for method chaining.

 


 

Ctrl& RightPosZ(int a, int size = STDSIZE)

Sets right horizontal zoomed position (in view area). Distances are recalculated using zoom factor to accommodate size differences between standard font used during layout design and actual standard font.

a

Distance from the right border of parent.

size

Horizontal size.

Return value    *this for method chaining.

 


 

Ctrl& TopPosZ(int a, int size = STDSIZE)

Sets top vertical zoomed position (in view area). Distances are recalculated using zoom factor to accommodate size differences between standard font used during layout design and actual standard font.

a

Distance from the top border of parent.

size

Vertical size.

Return value

*this for method chaining.

 


 

Ctrl& BottomPosZ(int a, int size = STDSIZE)

Sets bottom vertical zoomed position (in view area). Distances are recalculated using zoom factor to accommodate size differences between standard font used during layout design and actual standard font.

a

Distance from the bottom border of parent.

size

Vertical size.

Return value

*this for method chaining.

 


 

Ctrl& HSizePosZ(int a = 0, int b = 0)

Sets vertical zoomed sizing position (in view area). Distances are recalculated using zoom factor to accommodate size differences between standard font used during layout design and actual standard font.

a

Distance form top border of parent.

b

Distance from bottom border of parent.

Return value

*this for method chaining.

 


 

Ctrl& VSizePosZ(int a = 0, int b = 0)

Sets vertical zoomed sizing position (in view area). Distances are recalculated using zoom factor to accommodate size differences between standard font used during layout design and actual standard font.

a

Distance form top border of parent.

b

Distance from bottom border of parent.

Return value

*this for method chaining.

 


 

Ctrl& HCenterPosZ(int size = STDSIZE, int delta = 0)

Horizontal centered zoomed position (in view area). Distances are recalculated using zoom factor to accommodate size differences between standard font used during layout design and actual standard font.

size

Horizontal size.

delta

Offset from centered position (rarely used).

Return value

*this for method chaining.

 


 

Ctrl& VCenterPosZ(int size = STDSIZE, int delta = 0)

Vertical centered zoomed position (in view area). Distances are recalculated using zoom factor to accommodate size differences between standard font used during layout design and actual standard font.

size

Vertical size.

delta

Offset from centered position (rarely used).

Return value

*this for method chaining.

 


 

Rect GetRect() const

Return value

Returns current position in parent. It is either position in view or frame coordinates.

 


 

Rect GetScreenRect() const

Return value

Returns current position in absolute screen coordinates.

 


 

Rect GetView() const

Return value

Returns position of view rectangle in frame coordinates.

 


 

Rect GetScreenView() const

Return value

Returns position of view rectangle in absolute screen coordinates.

 


 

Size GetSize() const

Return value

Returns size of view rectangle of Ctrl.

 


 

Rect GetVisibleScreenRect() const

Return value

Returns current position in parent intersected with either parent's visible screen rectangle for frame Ctrl (as obtained using GetVisibleScreenRect) or parent's screen view rectangle for view Ctrl (obtained using GetVisibleScreenView). This method is useful when rectangle of Ctrl exceeds it's parent area - in this case this method returns part of Ctrl that is not clipped out by parent's are limits.

 


 

Rect GetVisibleScreenView() const

Return value

Returns current position of view area intersected with either parent's visible screen rectangle for frame Ctrl (as obtained using GetVisibleScreenRect) or parent's screen view rectangle for view Ctrl (obtained using GetVisibleScreenView). This method is useful when rectangle of Ctrl exceeds it's parent area - in this case this method returns part of Ctrl view that is not clipped out by parent's are limits.

 


 

Rect GetWorkArea() const

Returns the work area (the maximum rectangle that window can use) for screen that this window is in.

 


 

Size AddFrameSize(int cx, int cyconst

Computes size of Ctrl for given size of view and actual set of frames.

cx

Width.

cy

Height.

Return value

Size of Ctrl that would have requested view size.

 


 

Size AddFrameSize(Size szconst

Same as AddFrameSize(sz.cx, sz.cy).

sz

Size.

Return value

Size of Ctrl that would have requested view size.

 


 

void Refresh(const Rect& r)

Marks requested rectangle of view area for repainting. Actual repaint is deferred for performance reasons.

r

Rectangle in view.

 


 

void Refresh(int x, int y, int cx, int cy)

Marks requested rectangle of view area for repainting. Actual repaint is deferred for performance reasons.

x

Left position of rectangle.

y

Top position of rectangle.

cx

Width.

cy

Height.

 


 

void Refresh()

Marks whole view area for repainting.

 


 

bool IsFullRefresh() const

Return value

true when whole view area is marked for repainting but was not repainted yet.

 


 

void RefreshFrame(const Rect& r)

Marks requested rectangle of frame area for repainting. Actual repainting is deferred for performance reasons.

r

Area to repaint.

 


 

void RefreshFrame(int x, int y, int cx, int cy)

Marks requested rectangle of frame area for repainting. Actual repaint is deferred for performance reasons.

x

Left position of rectangle.

y

Top position of rectangle.

cx

Width.

cy

Height.

 


 

void RefreshFrame()

Marks whole Ctrl area for repainting.

 


 

void ScrollView(const Rect& r, int dx, int dy)

Marks requested view rectangle for repainting, indicating that part of this repaint can be done by scrolling current content of rectangle. Note that actual scroll is deferred to repaint and that U++ is still allowed to solve the situation by repainting rather than scrolling.

r

Area for repainting.

dx

Horizontal scroll.

dy

Vertical scroll.

 


 

void ScrollView(int x, int y, int cx, int cy, int dx, int dy)

Marks requested view rectangle for repainting, indicating that part of this repaint can be done by scrolling current content of rectangle. Note that actual scroll is deferred to repaint and that U++ is still allowed to solve the situation by repainting rather than scrolling.

r

Area for repainting.

x

Left position of rectangle.

y

Top position of rectangle.

cx

Width.

cy

Height.

dx

Horizontal scroll.

dy

Vertical scroll.

 


 

void ScrollView(int dx, int dy)

Marks while view area for repainting, indicating that part of this repaint can be done by scrolling current content of rectangle. Note that actual scroll is deferred to repaint and that U++ is still allowed to solve the situation by repainting rather than scrolling.

dx

Horizontal scroll.

dy

Vertical scroll.

 


 

void ScrollView(const Rect& r, Size delta)

Same as ScrollView(r, delta.cx, delta.cy).

 


 

void ScrollView(Size delta)

Same as ScrollView(delta.cx, delta.cy).

 


 

void Sync()

Forces immediate repainting of areas marked using Refresh, RefreshFrame or ScrollView methods.

 


 

void Sync(const Rect& r)

Forces immediate repainting of areas marked using Refresh, RefreshFrame or ScrollView methods, limited with intersection of given rectangle.

r

Rectangle.

 


 

static Image OverrideCursor(const Image& m)

Overrides mouse cursor to m. To end the override, call it again with the Image returned by the override call.

 


 

void DrawCtrl(Draw& w, int x = 0, int y = 0)

Draws Ctrl at specified position. This is intended for utility purposes like taking screen-shots. This version Draws Ctrl without background (supplied by parent).

w

Target Draw.

x, y

Position.

 


 

void DrawCtrlWithParent(Draw& w, int x = 0, int y = 0)

Draws Ctrl at specified position. This is intended for utility purposes like taking screen-shots. This version Draws Ctrl with background (supplied by parent).

w

Target Draw.

x, y

Position.

 


 

bool HasChild(Ctrl *ctrlconst

Tests whether Ctrl has specified direct child.

ctrl

Child.

Return value

true if ctrl is child.

 


 

bool HasChildDeep(Ctrl *ctrlconst

Tests whether Ctrl has specified ctrl in its child tree (direct or indirect).

ctrl

Child.

Return value

true if ctrl is in child tree.

 


 

Ctrl& IgnoreMouse(bool b = true)

Sets ignore-mouse flag. When active, Ctrl is ignored for mouse input. That is important for static Ctrls that cover other Ctrls, like LabelBox - this flag ensures, that mouse input is not consumed by LabelBox, but is distributed to Ctrls that lay inside it.

b

Value of flag.

Return value

*this for method chaining.

 


 

Ctrl& NoIgnoreMouse()

Same as IgnoreMouse(false).

Return value

*this for method chaining.

 


 

bool IsIgnoreMouse() const

Returns the ignore-mouse flag (see IgnoreMouse).

 


 

bool HasMouse() const

Return value

true when Ctrl is target for mouse events.

 


 

bool HasMouseDeep() const

Returns true if Ctrl or any of its descendants is target for mouse events.

 


 

bool HasMouseInFrame(const Rect& rconst

r

rectangle in frame area.

Return value

true when Ctrl is target for mouse events and mouse pointer is inside specified frame area rectangle.

 


 

bool HasMouseIn(const Rect& rconst

Returns true when Ctrl is target for mouse events and mouse pointer is inside specified view area rectangle.

 


 

Point GetMouseViewPos() const

Returns the position of mouse relative to the view area. Note that the result can negative point or point outside

 


 

static Ctrl *GetMouseCtrl()

Returns current target for mouse events.

 


 

static void IgnoreMouseClick()

Forces framework to ignore all mouse events till next button-up event. This is good tool to solve some corner cases, like popup window closed by button click when mouse pointer is over its owner as well (TopWindow::Close calls this function).

 


 

static void IgnoreMouseUp()

Invokes IgnoreMouseClick if some of mouse buttons is pressed.

 


 

static void UnIgnoreMouse()

Cancels the effect or IgnoreMouseClick and IgnoreMouseUp (clicks are not ignored anymore).

 


 

bool SetCapture()

Sets mouse capture for Ctrl. This method should be called in MouseLeft or MouseRight methods only. Ctrl will receive all mouse input until ReleaseCapture is called or mouse button is released.

Return value

True when SetCapture was successful (usually you can ignore this return value).

 


 

bool ReleaseCapture()

Release Ctrl's mouse capture.

Return value

True when mouse capture was released.

 


 

bool HasCapture() const

Return value

True if Ctrl has mouse capture.

 

 


 

static Ctrl *GetCaptureCtrl()

Returns a pointer to the Ctrl that is currently capturing the mouse.

 


 

static bool ReleaseCtrlCapture()

If any of application's Ctrls has mouse capture, it is released.

Return value

True if mouse capture was released.

 


 

bool SetFocus()

Sets keyboard input focus to the Ctrl. Ctrl is first to receive keyboard events via Key method as long as it has keyboard input focus. When Ctrl denies keyboard event (by returning false from Key method), it is passed to its parent's Key method and so on.

Return value

True if setting focus was successful.

 


 

bool HasFocus() const

Return value

True if Ctrl has keyboard input focus.

 


 

bool HasFocusDeep() const

Return value

True if Ctrl or any of its descendants has focus or is equal to GetOwnerCtrl of any active popup.

 


 

Ctrl& WantFocus(bool ft = true)

Indicates whether Ctrl wants focus to be passed to it by U++, when navigating through the dialog using Tab (or Shift+Tab) key.

ft

true to indicate that Ctrl wants focus.

Return value

Same Ctrl for method chaining.

 


 

Ctrl& NoWantFocus()

Return value

Same Ctrl for method chaining.

 


 

bool IsWantFocus() const

Checks whether Ctrl has WantFocus acti.

Return value

true, when Ctrl wants focus.

 


 

Ctrl& InitFocus(bool ft = true)

Indicates that Ctrl is eligible to obtain focus upon opening of dialog or in other similar situations.

ft

true to indicate Ctrl is eligible.

Return value

Same Ctrl for method chaining.

 


 

Ctrl& NoInitFocus()

Same as InitFocus(false).

Return value

Same Ctrl for method chaining.

 


 

bool IsInitFocus()

Return value

true when Ctrl wants init focus.

 


 

bool SetWantFocus()

If Ctrl wants focus (WantFocus(true) was called for it), set focus to Ctrl, otherwise nothing happens.

Return value

true if focus was set.

 


 

Ctrl *GetFocusChild() const

If any immediate child of Ctrl has focus, returns pointer to it.

Return value

Pointer to child with focus or NULL if no such exists.

 


 

Ctrl *GetFocusChildDeep() const

If any child of Ctrl's child tree has focus, returns pointer to it.

Return value

 


 

void CancelModeDeep()

Calls CancelMode virtual method for Ctrl and all of its descendants.

 


 

void CancelPreedit()

Terminates any input method composition in progress, if possible. Text input widgets typically call this on status change, like new cursor position or new text through SetData.

 


 

void CancelMyPreedit()

Calls CancelPreedit if this widget has keyboard focus.

 


 

static Ctrl *GetFocusCtrl()

Return value

Ctrl that has focus or NULL if no Ctrl of application has it.

 


 

static bool IterateFocusForward(Ctrl *ctrl, Ctrl *top, bool noframe = false, bool init = false, bool all = false)

Tries to move focus to next "appropriate" Ctrl, like when Tab key is pressed in the dialog. Appropriate Ctrl needs to have WantFocus flag, be visible and enabled.

ctrl

Ctrl with focus.

top

Top Ctrl - function cycles only between this Ctrl subtree.

noframe

Indicates that frame Ctrls are to be excluded.

Return value

true when focus was successfully moved.

 


 

static bool IterateFocusBackward(Ctrl *ctrl, Ctrl *top, bool noframe = false, bool all = false)

Tries to move focus to previous appropriate Ctrl, like when Tab key is pressed in the dialog. "Appropriate" Ctrl needs to have WantFocus flag, be visible and enabled.

ctrl

Ctrl with focus.

top

Top Ctrl - function cycles only between this Ctrl subtree.

noframe

Indicates that frame Ctrls are to be excluded.

init

Ctrl must have InitFocus flag.

Return value

true when focus was successfully moved.

 


 

static dword AccessKeyBit(byte accesskey)

Returns bit-mask for specified access-key.

accesskey

Access-key. It should be plain ASCII value of access-key.

Return value

Access-key bitmask. Note that only 'A' - 'Z' have distinct bit-masks as those are only access-keys distributed automatically.

 


 

dword GetAccessKeysDeep() const

dword GetAccessKeysDeep() const

Returns binary or of Ctrl's GetAccessKey method results with the result of calling GetAccessKeyDeep for all children. In other words, returns key coverage for the whole Ctrl tree.

Return value

Access-keys used by Ctrl and its descendants.

 


 

void DistributeAccessKeys()

Triggers automatic distribution of access keys. This is implemented as gathering all already used access keys using GetAccessKeys method and then using AssignAccessKeys method with this value to distribute rest of keys (in other words, it is equivalent of AssignAccessKeys(GetAccessKeys())).

 


 

void RefreshAccessKeys()

Invokes Refresh for this Ctrl or any descendant with any access-key assigned.

 


 

bool VisibleAccessKeys()

Return value

True if according to current access-key model there should be visible graphical representation (usually underline) of access-keys.

 


 

void Show(bool show = true)

Sets visibility flag for Ctrl.

show

true indicates that Ctrl should be visible.

 


 

void Hide()

Same as Show(false).

 


 

bool IsShown() const

Return value

visibility flag for Ctrl.

 


 

bool IsVisible() const

Return value

true if Ctrl is currently visible on the screen. Ctrl is visible if it has visibility flag set, its parent is visible and its top-level Ctrl is open.

 


 

void Enable(bool enable = true)

Enables or disables Ctrl.

enable

true indicates that Ctrl should be enabled.

 


 

void Disable()

Same as Enable(false).

 


 

bool IsEnabled() const

Return value

true if Ctrl is enabled.

 


 

Ctrl& SetEditable(bool editable = true)

Sets editable or read-only mode of Ctrl. Specific Ctrls can check this flag using IsEditable method and behave accordingly.

editable

true indicates that Ctrl is editable.

Return value

*this for method chaining.

 


 

Ctrl& SetReadOnly()

Same as SetEditable(false).

 


 

bool IsEditable() const

Return value

true if Ctrl is editable.

 


 

bool IsReadOnly() const

Same as !IsEditable().

 


 

void ClearModifyDeep()

Clear modify flag (by calling ClearModify) for the widgets and all its descendants.

 


 

bool IsModifiedDeep() const

Returns true if widget or any of its descendants have modify flag active.

 


 

void UpdateRefresh()

Calls both Update and Refresh methods.

 


 

void Update()

Same as SetModify().

 


 

void Action()

Invokes default Ctrl callback - WhenAction. Action actually makes a copy of WhenAction - this ensures that the Event<> object is not destroyed during the call.

 


 

void UpdateAction()

Calls Update and then Action.

 


 

void UpdateActionRefresh()

Calls Update, then Action, then Refresh. Typically called after user changes values of Ctrl.

 


 

Ctrl& Transparent(bool bp = true)

Sets transparency flag of Ctrl. If transparency flag is disabled, U++ can paint Ctrl in more effective way.

bp

Transparency flag.

Return value

*this for method chaining.

 


 

Ctrl& NoTransparent()

Return value

Transparent(false).

 


 

bool IsTransparent() const

Return value

Value of transparency flag.

 


 

Ctrl& ActiveX(bool ax = true)

Special flag used for ActiveX Ctrls implementation.

Windows specific.

ax

true - Ctrl is ActiveX control

Return value

*this for method chaining.

 


 

Ctrl& NoActiveX()

Return value

ActiveX(false).

 


 

bool IsActiveX() const

Return value

Value of ActiveX flag.

 


 

Ctrl& HelpLine(const char *txt)

Sets help topic link for Ctrl.

txt

Link.

Return value

*this for method chaining.

 


 

String GetTip() const

Return value

Current Tip text.

 


 

String GetHelpLine() const

Return value

Current HelpTopic link.

 


 

Ctrl& operator<<(Ctrl& ctrl)

void Add(Ctrl& ctrl)

Adds ctrl as the last child.

ctrl

Ctrl to add.

 


 

void Remove()

Removes Ctrl from its parent.

 


 

const Value& operator<<=(const Value& v)

Same as SetData(v).

v

New Value of Ctrl.

Return value

Reference to v.

 


 

Callback& operator<<(Upp::Function<void ()> action)

Same as WhenAction << action, can be used both with lambdas and Events (former Callbacks)..

 


 

void SetTimeCallback(int delay_ms, Function<void ()> cb, int id = 0)

Puts delayed callback to the timer queue. As an identifier of callback, which is void * in timer queue, this + id is used. When Ctrl is destroyed, all callbacks with id in range 0 ... sizeof(Ctrl) are removed from timer callback queue - this ensures that no dangling callbacks are left there.

delay_ms is delay of callback in ms. If this is 0, callback is called immediately after all pending input GUI events are processed. Negative value means the event is periodic - it is triggered after -delay_ms and after being performed, it is rescheduled with the same delay_ms.

Identifier id should be in range 0..80. U++ defines compile-time protocol for distributing these ids. If Ctrl wants to use non-zero time callback id, it should define it using

 

    enum { TIMEID_PERIODIC = baseclass::TIMEID_COUNT, TIMEID_COUNT };

 

    Using zero as id is OK as long as you do not intend to remove time callbacks using KillTimeCallback. Alternative to using id is class TimeCallback that represents whole issue as member variable of Ctrl.

 


 

void KillTimeCallback(int id = 0)

Removes time callback associated with Ctrl.

id

Id of callback.

 


 

void KillSetTimeCallback(int delay_ms, Function<void ()> cb, int id)

Removes callback with id and sets it again.

 


 

bool ExistsTimeCallback(int id = 0const

Tests whether Ctrl has associated callback in timer queue.

id

Id of callback.

Return value

true when id is found in timer queue.

 


 

void PostCallback(Function<void ()> cb, int id = 0)

Posts callback to be executed immediately (but in the main loop after all current GUI events).

 


 

void KillPostCallback(Function<void ()> cb, int id)

Similar to PostCallback, but removes callback(s) with the same id from the queue first.

 


 

static Ctrl *GetActiveCtrl()

Returns pointer to active Ctrl. Active Ctrl is top-level Ctrl of Ctrl with keyboard focus.

Return value

Pointer to active Ctrl.

 


 

static Ctrl *GetActiveWindow()

Returns pointer to active TopWindow that is either active or owns active Ctrl. Difference between GetActiveWindow and GetActiveCtrl is that GetActiveCtrl can return pop-up Ctrl, while GetActiveWindow returns always TopWindow - if active Ctrl is pop-up, owner of pop-up is returned.

Return value

Pointer to active window.

 


 

static Ctrl *GetVisibleChild(Ctrl *ctrl, Point p, bool pointinframe)

Finds deepest descendant of Ctrl that is visible and contains given point. If not such Ctrl exists, returns this.

ctrl

Parent ctrl.

p

Point.

pointinframe

Determines whether point is in view or frame coordinates.

Return value

Pointer to Ctrl.

 


 

void PopUpHWND(HWND hwnd, bool savebits = true, bool activate = true, bool dropshadow = false, bool topmost = false)

Opens top-level Ctrl as pop-up window. This method can only be invoked in the main thread.

Win32 specific.

hwnd

Win32 handle of owner window.

savebits

Indicates that system should try to preserve background bits.

activate

Pop-up should be activated.

dropshadow

Pop-up should have drop-shadow (if supported).

topmost

Pop-up should be top-most window.

 


 

void PopUp(Ctrl *owner = NULL, bool savebits = true, bool activate = true, bool dropshadow = false, bool topmost = false)

Opens top-level Ctrl as pop-up window. This method can only be invoked in the main thread.

owner

Owner.

savebits

Indicates that system should try to preserve background bits.

activate

Pop-up should be activated.

dropshadow

Pop-up should have drop-shadow (if supported).

topmost

Pop-up should be top-most window.

 


 

void SetAlpha(byte alpha)

Sets top-level Ctrl alpha blending if supported by system. Ctrl must be open.

alpha

Value of alpha.

 


 

static bool IsWaitingEvent()

Return value

True when there is waiting unprocessed event in input queue.

 


 

static bool ProcessEvent(bool *quit = NULL)

Processes single event from input queue. When there is no pending event, returns immediately. (Processing event involves usually involves dispatching it via virtual methods to proper Ctrls).

quit

Assigned true when WM_QUIT message is intercepted (Win32 specific).

Return value

True indicates that event was processed, false that queue was empty.

 


 

static bool ProcessEvents(bool *quit = NULL)

Processes all events from input queue. When there is no pending event, returns immediately. (Processing event involves usually involves dispatching it via virtual methods to proper Ctrls).

quit

Assigned true when WM_QUIT message is intercepted (Win32 specific).

Return value

True indicates that one or more events were processed, false that queue was empty.

 


 

static int GetEventLevel()

Returns the level of input event. This is basically a reentrancy level of ProcessEvent(s) routine - it starts zero but increments each time the input event is generated by ProcessEvent(s). This information can be useful for background threads or in timer events (where this is zero when application is in the "base" state).

 


 

bool IsPopUp() const

Return value

True if Ctrl is pop-up window.

 


 

static void EventLoop(Ctrl *loopctrl = NULL)

Executes event-loop. If loopctrl is not NULL, it must be opened top-level Ctrl and loop is executed until EndLoop method for loopctrl is invoked. If loopctrl is NULL, loop is executed as long as any top-level Ctrl exists or application is terminated by OS specific "shutdown" event. This method can only be invoked in the main thread.

loopctrl

Looping Ctrl.

 


 

static int GetLoopLevel()

Return value

Level of even-loop (even-loops a reentrant).

 


 

static Ctrl *GetLoopCtrl()

Return value

Current looping Ctrl.

 


 

void EndLoop()

Terminates loop for looping Ctrl. Note that this terminates only loop for looping Ctrl. If there is another loop above such loop, nothing is terminated until this additional loop is active.

 


 

void EndLoop(int code)

Same as EndLoop(), but also defines loop exit code.

code

Loop exit code.

 


 

bool InLoop() const

Return value

true if Ctrl is looping Ctrl.

 


 

int GetExitCode() const

Return value

Exit code of last loop performed with this Ctrl.

 


 

static PasteClip& Clipboard()

Represents the clipboard as PasteClip. This allows unification of drag&drop and clipboard operations as there can be single method handling with Clipboard and Drag&Drop (and X11 selection) operations.

 


 

static PasteClip& Selection()

Represents X11 selection as PasteClip. This allows unification of drag&drop and selection operations as there can be single method handling with Clipboard and Drag&Drop (and X11 selection) operations.

 


 

void SetSelectionSource(const char *fmts)

Tells X11 system that this Ctrl is current selection source, with fmts available (semicolon separated list).

 


 

int DoDragAndDrop(const char *fmts, const Image& sample, dword actions, const VectorMap<String, ClipData>& data)

Performs drag&drop operation, with this Ctrl as source. fmts is a semicolon separated list of formats available using GetDropData method, sample is an image representation of data, actions are allowed drag and drop operations - a binary or DND_NONE, DND_COPY, DND_MOVE (or DND_ALL as combination of all of them). Special unrelated flag DND_EXACTIMAGE can be add to actions to indicate that Drag&Drop should not alter sample image (otherwise it can be adjusted to look consistent). data is data directly provided for the operation as map of individual formats to ClipData.

 


 

int DoDragAndDrop(const char *fmts, const Image& sample = Null, dword actions = DND_ALL)

DoDragAndDrop with empty data (all formats are provided by GetDropData).

 


 

int DoDragAndDrop(const VectorMap<String, ClipData>& data, const Image& sample = Null, dword actions = DND_ALL)

DoDragAndDrop with empty fmts (all formats are provided by data).

 


 

static Ctrl *GetDragAndDropSource()

Returns current source of Drag and Drop, is such source exists in this process and it is U++ widget (otherwise returns NULL).

 


 

static Ctrl *GetDragAndDropTarget()

Returns current target of Drag and Drop, is such target exists in this process and it is U++ widget (otherwise returns NULL).

 


 

bool IsDragAndDropSource()

Same as this == GetDragAndDropSource().

 


 

bool IsDragAndDropTarget()

Same as this == GetDragAndDropTarget().

 


 

static Size StdSampleSize()

Returns the best size of DoDragAndDrop sample parameter.

 


 

void SetMinSize(Size sz)

This method does nothing. It is a interface placeholder to get Layout templates working - in derived classes this can be statically overloaded to receive minimal size of layout.

sz

Minimal size of layout.

 


 

static void Csizeinit()

Sets zoom factor used to scale layouts (to scale zoomed positioning methods like LeftPosZ). Horizontal distances are scaled by sz.cx / bsz.cx, vertical by sz.cy / bsz.cy. If bsz is Size(0, 0), default base size (based on standard Win32 GUI font) is used. Note that U++ sets scaling factor automatically upon startup based on actual standard GUI font size.

sz

Numerator of scaling factor.

bsz

Denominator of scaling factor.

 


 

static int HorzLayoutZoom(int cx)

Performs horizontal scaling by actual scaling factor.

cx

Distance to scale.

Return value

Scaled distance.

 


 

double HorzLayoutZoomf(double cx)

Similar to HorzLayoutZoom, but with double precision.

 


 

static int VertLayoutZoom(int cy)

Performs vertical scaling by actual scaling factor.

cy

Distance to scale.

Return value

Scaled distance.

 


 

static Size LayoutZoom(int cx, int cy)

Performs scaling by actual scaling factor.

cx

Horizontal distance.

cy

Vertical distance.

Return value

Scaled size.

 


 

static Size LayoutZoom(Size sz)

Performs scaling by actual scaling factor.

sz

Size to scale.

Return value

Scaled size.

 


 

static void NoLayoutZoom()

Sets scaling factor to (1, 1). Same as SetZoomSize(Size(1, 1), Size(1, 1)).

 


 

void SetUHDEnabled(bool set)

Informs host platform that application is UHD ready. Default is true. Disabling UHD mode has to be done before GUI_APP_MAIN, e.g. in INITBLOCK.

 


 

bool IsUHDEnabled()

Returns the value set by SetUHDEnabled.

 


 

static void SetDarkThemeEnabled(bool set = true)

Hints coloring and skinning algorithms that the application is ready to work in dark theme mode. Currently this enables dark theme in Windows (with other platforms dark theme is enabled by default). Default value is true. Disabling dark theme has to be done before GUI_APP_MAIN, e.g. in INITBLOCK.

 


 

static bool IsDarkThemeEnabled()

Returns the value set by SetDarkThemeEnabled.

 


 

Rect GetWorkArea()

Returns OS specific working area for the widget - this is rectangle in screen coordinates where application top-level windows can be placed - the size of screen minus the size of any border entities like the task-bar. If widget is not associated with the open window, returns the size of primary work area.

Return value

Work area rectangle.

 


 

static Rect GetVirtualWorkArea()

Returns the total size of all displays minus any border entities.

 


 

static Rect GetVirtualScreenArea()

Returns the total size of all displays.

 


 

static Rect GetPrimaryWorkArea()

Returns the size of primary work area - primary screen in Windows is the display with start menu.

 


 

static Rect GetPrimaryScreenArea()

Returns the size of primary screen - primary screen in Windows is the display with start menu.

 


 

static Rect GetWorkArea(Point pt)

Returns the recangle of work area which contains pt. If pt does not belong to any area, returns the primary work area.

 


 

static Rect GetMouseWorkArea()

Returns the work are which contains mouse cursor. Same as GetWorkArea(GetMousePos()).

 


 

static int GetKbdDelay()

Returns delay of keyboard before autorepeat starts when key is pressed.

Return value

Time in ms.

 


 

static int GetKbdSpeed()

Returns speed of autorepeat.

Return value

Speed of autorepeat.

 


 

static Rect GetDefaultWindowRect()

Returns OS suggested rectangle of newly open window.

Return value

Default window rectangle.

 


 

static String GetAppName()

Return value

Name of application. Used by U++ in several places like Prompts.

 


 

static void SetAppName(const String& appname)

appname

Adjusts application name.

 


 

String Name() const

Dumps diagnostic informations to standard log.

 


 

virtual void Dump(Stream& sconst

Dumps diagnostic informations to specified output stream.

s

Stream.

 


 

static void GuiSleep(int ms)

Sleeps (while allowing other applications or threads to run) for at least ms milliseconds or until new input event is available. This method can only be invoked in the main thread.

ms

Time to sleep.

 


 

static void Call(Function<void ()> cb)

Executes a callback in the main thread (the one responsible for GUI). It works by posting callback into timer queue (with zero delay), then waits its completion using Semaphore. Main GUI thread has to run timer queue management for callback to be executed (by running event-loop (TopWindow::Run) or ProcessEvents). Warning: Call temporarily unlocks GuiLock (if locked) so that the main thread can run on GUI, this is possible source of race-conditions (GuiLock is relocked after call completes). Be prepared that some other code can run on GUI between call to Call and cb being executed!

 


 

static bool IsShutdownThreads()

Same as Thread::IsShutdownThreads. Used to signal non-main threads that the program is about to end, so that non-main threads should terminate.

 


 

static void ShutdownThreads()

Similiar to Thread::ShutdownThreads, but as part of waiting for threads to finish calls ProcessEvents so that any Call methods can finish and also periodically unlocks GuiLock so that threads waiting on it can finish.

 


 

static int64 GetEventId()

This function is guaranteed to return the same number while single input event (mouse event or keyboard event) is processed. This is helpful in certain caching situations - e.g. if you want to lazy fetch some data, but only once per input event.

 


 

CtrlConstIterator begin() const

CtrlIterator begin()

CtrlConstIterator end() const

CtrlIterator end()

Adds rudimentary iterators over child widgets. Allows range-based for loops: for(Ctrl& q : widget).

 

 

Ctrl::Logc

 

class Logc

This nested class serves as either vertical or horizontal part of logical position.

 

 

Constructor Detail

 

Logc(int al, int a, int b)

al

Alignment type. Determines what other parameters mean.

a

First value.

b

Second value.

 


 

Logc()

Default constructor. Sets Logc to the empty state.

 

 

Public Member List

 

static int LSGN(dword d)

q

Logc to compare with.

Return value

True when equal.

 


 

bool operator!=(Logc qconst

q

Logc to compare with.

Return value

True when not equal.

 


 

int GetAlign() const

Return value

Alignment type.

 


 

int GetA() const

Return value

First value.

 


 

int GetB() const

Return value

Second value.

 


 

void SetAlign(int align)

Sets alignment type.

align

Alignment type.

 


 

void SetA(int a)

Sets first value.

a

Value.

 


 

void SetB(int b)

Sets second value.

b

Value.

 


 

bool IsEmpty() const

Return value

True if Logc is empty.

 

 

 

 

Ctrl::LogPos

 

struct LogPos

This nested class combines two Logc value into complete logical position.

 

 

Constructor Detail

 

LogPos(Logc x, Logc y)

x

Horizontal Logc.

y

Vertical Logc.

 


 

LogPos()

Default constructor. Sets both Logc empty.

 

 

Public Member List

 

bool operator==(LogPos bconst

b

LogPos to compare with.

Return value

True when equal.

 


 

bool operator!=(LogPos bconst

b

LogPos to compare with.

Return value

True when equal.

 


 

Logc x

Horizontal Logc.

 


 

Logc y

Vertical Logc.

 

 

Do you want to contribute?