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").

enum PlacementConstants

Constants used in logical coordinates.

enum StateReason

Arguments of State virtual method.

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

Actions

Buttons

Combinations

enum { NOBACKPAINT, FULLBACKPAINT, TRANSPARENTBACKPAINT, EXCLUDEPAINT }

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

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).

static Logc PosRight(int pos, int size)

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

static Logc PosTop(int pos, int size)

Equal to PosLeft(pos, size).

static Logc PosBottom(int pos, int size)

Equal to PosRight(pos, size).

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).

static Logc PosCenter(int size, int offset)

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

static Logc PosCenter(int size)

Equal to PosCenter(size, 0).

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.

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.

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).

static void DeinstallMouseHook(MouseHook hook)

Uninstalls previously installed mouse hook.

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).

static void DeinstallKeyHook(KeyHook hook)

Uninstalls previously installed keyboard hook.

static void InstallStateHook(StateHook hook)

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

static void DeinstallStateHook(StateHook hook)

Deinstalls previously installed state hook.

virtual void Paint(Draw& draw)

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

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().

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.

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.

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.

virtual void LeftDown(Point p, dword keyflags)

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

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.

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.

virtual void LeftUp(Point p, dword keyflags)

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

virtual void RightDown(Point p, dword keyflags)

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

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.

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.

virtual void RightUp(Point p, dword keyflags)

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

virtual void MiddleDown(Point p, dword keyflags)

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

virtual void MiddleDouble(Point p, dword keyflags)

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

virtual void MiddleTriple(Point p, dword keyflags)

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

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.

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.

virtual void MiddleUp(Point p, dword keyflags)

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

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.

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& fmt) const

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& fmt) const

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

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.

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.

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.

virtual void AssignAccessKeys(dword used)

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

virtual void ChildAdded(Ctrl *child)

This method is invoked when child is added to Ctrl.

virtual void ChildRemoved(Ctrl *child)

This method is invoked when child is removed from Ctrl.

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.

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.

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.

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,

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.

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.

void AddChildBefore(Ctrl *child, Ctrl *insbefore)

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

void RemoveChild(Ctrl *child)

Removes Ctrl from child list. Ctrl is never deleted.

Ctrl *GetParent() const

Returns parent of Ctrl or NULL if Ctrl is topmost.

Ctrl *GetLastChild() const

Returns last child.

Ctrl *GetFirstChild() const

Returns first child.

Ctrl *GetPrev() const

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

Ctrl *GetNext() const

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

int GetChildIndex(const Ctrl *child) const

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 T> T *GetAscendant() const

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

Ctrl *GetIndexChild(int i) const

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 *child) const

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 ii) const

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

Ctrl *ChildFromPoint(Point& pt) const

Checks whether opened top-level 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.

Ctrl *GetTopCtrl()

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

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.

Ctrl *GetOwner()

Returns owner of top-level Ctrl.

const Ctrl *GetTopCtrlOwner() const

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

Ctrl *GetTopCtrlOwner()

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

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.

TopWindow *GetTopWindow()

TopWindow that contains this Ctrl.

const TopWindow *GetMainWindow() const

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

TopWindow *GetMainWindow()

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

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.

Ctrl& SetFrame(CtrlFrame& frm)

Sets frame at position 0.

Ctrl& AddFrame(CtrlFrame& frm)

Adds frame at inner-most position.

const CtrlFrame& GetFrame(int i = 0) const

Returns reference to frame at given position.

CtrlFrame& GetFrame(int i = 0)

Returns reference to frame at given position.

void RemoveFrame(int i)

Removes frame at given position.

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).

void InsertFrame(int i, CtrlFrame& frm)

Inserts frame at given position.

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).

int GetFrameCount() const

Returns count of frames in Ctrl.

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.

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.

Ctrl& SetPos(LogPos p, bool inframe)

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

Ctrl& SetPos(LogPos p)

Sets logical position of Ctrl in view area.

Ctrl& SetPos(Logc x, Logc y)

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

Ctrl& SetPosX(Logc x)

Sets horizontal logical position only (in view area).

Ctrl& SetPosY(Logc y)

Sets vertical logical position only (in view area).

void SetRect(const Rect& r)

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

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

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

void SetRectX(int x, int cx)

Sets left horizontal logical position (in view area).

void SetRectY(int y, int cy)

Sets top vertical logical position (in view area).

Ctrl& SetFramePos(LogPos p)

Sets logical position of Ctrl in frame area.

Ctrl& SetFramePos(Logc x, Logc y)

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

Ctrl& SetFramePosX(Logc x)

Sets horizontal logical position only (in frame area).

Ctrl& SetFramePosY(Logc y)

Sets vertical logical position only (in frame area).

void SetFrameRect(const Rect& r)

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

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

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

void SetFrameRectX(int x, int cx)

Sets left horizontal logical position (in frame area).

void SetFrameRectY(int y, int cy)

Sets top vertical logical position (in frame area).

bool InFrame() const

bool InView() const

LogPos GetPos() const

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).

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

Sets right horizontal position (in view area).

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

Sets top vertical position (in view area).

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

Sets bottom vertical position (in view area).

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

Sets horizontal sizing position (in view area).

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

Sets vertical sizing position (in view area).

Ctrl& SizePos()

Same as VSizePos().HSizePos().

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

Horizontal centered position (in view area).

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

Vertical centered position (in view area).

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.

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.

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.

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.

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.

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.

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.

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.

Rect GetRect() const

Rect GetScreenRect() const

Rect GetView() const

Rect GetScreenView() const

Size GetSize() const

Rect GetVisibleScreenRect() const

Rect GetVisibleScreenView() const

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 cy) const

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

Size AddFrameSize(Size sz) const

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

void Refresh(const Rect& r)

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

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.

void Refresh()

Marks whole view area for repainting.

bool IsFullRefresh() const

void RefreshFrame(const Rect& r)

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

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.

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.

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.

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.

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.

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).

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).

bool HasChild(Ctrl *ctrl) const

Tests whether Ctrl has specified direct child.

bool HasChildDeep(Ctrl *ctrl) const

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

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.

Ctrl& NoIgnoreMouse()

Same as IgnoreMouse(false).

bool IsIgnoreMouse() const

Returns the ignore-mouse flag (see IgnoreMouse).

bool HasMouse() const

bool HasMouseDeep() const

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

bool HasMouseInFrame(const Rect& r) const

bool HasMouseIn(const Rect& r) const

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.

bool ReleaseCapture()

Release Ctrl's mouse capture.

bool HasCapture() const

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.

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.

bool HasFocus() const

bool HasFocusDeep() const

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.

Ctrl& NoWantFocus()

bool IsWantFocus() const

Checks whether Ctrl has WantFocus acti.

Ctrl& InitFocus(bool ft = true)

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

Ctrl& NoInitFocus()

Same as InitFocus(false).

bool IsInitFocus()

bool SetWantFocus()

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

Ctrl *GetFocusChild() const

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

Ctrl *GetFocusChildDeep() const

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

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()

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.

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.

static dword AccessKeyBit(byte accesskey)

Returns bit-mask for specified access-key.

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.

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()

void Show(bool show = true)

Sets visibility flag for Ctrl.

void Hide()

Same as Show(false).

bool IsShown() const

bool IsVisible() const

void Enable(bool enable = true)

Enables or disables Ctrl.

void Disable()

Same as Enable(false).

bool IsEnabled() const

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.

Ctrl& SetReadOnly()

Same as SetEditable(false).

bool IsEditable() const

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.

Ctrl& NoTransparent()

bool IsTransparent() const

Ctrl& ActiveX(bool ax = true)

Special flag used for ActiveX Ctrls implementation.

Windows specific.

Ctrl& NoActiveX()

bool IsActiveX() const

Ctrl& HelpLine(const char *txt)

Sets help topic link for Ctrl.

String GetTip() const

String GetHelpLine() const

Ctrl& operator<<(Ctrl& ctrl)

void Add(Ctrl& ctrl)

Adds ctrl as the last child.

void Remove()

Removes Ctrl from its parent.

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

Same as SetData(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.

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

Removes callback with id and sets it again.

bool ExistsTimeCallback(int id = 0) const

Tests whether Ctrl has associated callback 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.

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.

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.

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.

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.

void SetAlpha(byte alpha)

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

static bool IsWaitingEvent()

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).

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).

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

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.

static int GetLoopLevel()

static Ctrl *GetLoopCtrl()

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.

bool InLoop() const

int GetExitCode() const

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.

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.

static int HorzLayoutZoom(int cx)

Performs horizontal scaling by actual scaling factor.

double HorzLayoutZoomf(double cx)

Similar to HorzLayoutZoom, but with double precision.

static int VertLayoutZoom(int cy)

Performs vertical scaling by actual scaling factor.

static Size LayoutZoom(int cx, int cy)

Performs scaling by actual scaling factor.

static Size LayoutZoom(Size sz)

Performs scaling by actual scaling factor.

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.

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.

static int GetKbdSpeed()

Returns speed of autorepeat.

static Rect GetDefaultWindowRect()

Returns OS suggested rectangle of newly open window.

static String GetAppName()

static void SetAppName(const String& appname)

String Name() const

Dumps diagnostic informations to standard log.

virtual void Dump(Stream& s) const

Dumps diagnostic informations to specified output 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.

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).

class Logc

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

Logc(int al, int a, int b)

Logc()

Default constructor. Sets Logc to the empty state.

static int LSGN(dword d)

bool operator!=(Logc q) const

int GetAlign() const

int GetA() const

int GetB() const

void SetAlign(int align)

Sets alignment type.