Root base class for all user interface objects. More...

#include <UIObject.h>

Inheritance diagram for pcl::UIObject:

Public Member Functions
virtual	~UIObject () noexcept(false)

virtual void	EnsureUnique ()

bool	IsAlias () const

bool	IsGarbage () const

bool	IsNull () const

bool	IsSameObject (const UIObject &o) const

bool	IsUnique () const

String	ObjectId () const

IsoString	ObjectType () const

bool	operator< (const UIObject &o) const

bool	operator== (const UIObject &o) const

size_type	RefCount () const

void	SetObjectId (const String &id)

Static Public Member Functions
static UIObject &	Null ()

Protected Member Functions
	UIObject ()=default

	UIObject (const UIObject &x)

	UIObject (UIObject &&x)

UIObject &	operator= (const UIObject &x)

UIObject &	operator= (UIObject &&x)

Detailed Description

UIObject is a high-level, managed client-side interface to a server-side object living in the PixInsight core application. UIObject is the root base class of all PCL classes representing objects that can be constructed and destroyed in the PixInsight platform, such as most user interface elements, file format instances, and process instances.

For example, Bitmap and ProcessInstance are derived classes of UIObject because you can generate new instances of the server-side objects represented by these classes. Contrarily, FileFormat and Process are not UIObject descendants because these classes represent installed components that cannot be created or modified by a module.

All the server-side objects represented by UIObject and its derived classes are reference counted objects. When you create an instance of UIObject (or a derived class) in your module, you either generate a new object in the platform, or increase the reference counter of an already existing object. When a server-side object becomes unreferenced, that is, when no living UIObject represents it, it is either destroyed or recycled by the PixInsight core application as soon as possible, in order to reuse and optimize the available resources. This process is known as garbage collection, and works in a completely automatic and transparent fashion in the PixInsight platform.

Definition at line 94 of file UIObject.h.

Constructor & Destructor Documentation

◆ ~UIObject()

virtual pcl::UIObject::~UIObject ( )

virtualnoexcept

Virtual destructor.

After destruction of this UIObject, the server-side object is also destroyed or recycled if it is no longer referenced by other high-level interfaces (e.g., other instances of UIObject in this or other modules).

◆ UIObject() [1/3]

pcl::UIObject::UIObject ( )

protecteddefault

Constructs a null UIObject instance.

A null UIObject does not correspond to an existing object in the PixInsight core application.

◆ UIObject() [2/3]

pcl::UIObject::UIObject ( const UIObject & x )

protected

Copy constructor.

Unless a derived class redefines it otherwise (which is rare), this constructor does not create a new object in the PixInsight core application. It simply creates an alias UIObject instance that references the same server-side object as the source instance x.

◆ UIObject() [3/3]

pcl::UIObject::UIObject ( UIObject && x )

inlineprotected

Move constructor.

Definition at line 304 of file UIObject.h.

Member Function Documentation

◆ EnsureUnique()

virtual void pcl::UIObject::EnsureUnique ( )

virtual

Ensures that the server-side object managed by this instance is uniquely referenced.

If there are other UIObject instances that refer to the same server-side object, this member function attempts to create a new server-side object as a copy of the currently managed object, and references it.

If the server-side object is only referenced by this UIObject instance, calling this member function has no effect.

Some derived classes represent object types whose instances are unique by nature. In those cases, calling this member function has no effect.

Reimplemented in pcl::Timer, pcl::Thread, pcl::Sizer, pcl::ReadWriteMutex, pcl::NetworkTransfer, pcl::GraphicsContextBase, pcl::FileFormatInstance, pcl::ExternalProcess, pcl::Control, and pcl::Action.

◆ IsAlias()

bool pcl::UIObject::IsAlias ( ) const

inline

Returns true iff this UIObject instance is an alias to an existing object in the calling module.

An alias and its aliased object are interchangeable; other than module-specific functionality, their behaviors are identical since they refer to a unique object living in the PixInsight core application. An alias UIObject is generated each time a new UIObject descendant class is instantiated using (explicitly or indirectly) a copy constructor. For example:

ImageWindow w1( 256, 256 ); // ImageWindow is an UIObject derived class
ImageWindow w2 = w1;    // w2 is an alias to w1.
bool b1 = w1.IsAlias(); // b1 is now false
bool b2 = w2.IsAlias(); // b2 is now true
w2.Show(); // OK, shows w1.
w1.HideMask();
bool b3 = w2.IsMaskVisible(); // b3 is now false
w2.Close(); // OK, the window is destroyed and both w1 and w2 are now invalid objects.

The only limit specific to aliased objects is the fact that an alias Control (or descendant) cannot set event handlers. See the documentation for Control( const Control& ) for more information.

Definition at line 174 of file UIObject.h.

◆ IsGarbage()

bool pcl::UIObject::IsGarbage ( ) const

inline

Returns true iff this managed object represents an unreferenced server-side object. Such objects are said to be 'garbage' in the programming jargon, and are subject to eventual destruction through a process known as garbage collection.

Definition at line 185 of file UIObject.h.

◆ IsNull()

bool pcl::UIObject::IsNull ( ) const

inline

Returns true iff this is a null UIObject instance.

A null UIObject does not represent an existing object in the PixInsight core application.

Definition at line 113 of file UIObject.h.

◆ IsSameObject()

bool pcl::UIObject::IsSameObject ( const UIObject & o ) const

inline

Returns true iff this instance and other UIObject o reference the same server-side object.

If two UIObject instances reference the same server-side object, each of them act as an alias for the other: In all respects, both high-level instances are interchangeable.

Definition at line 198 of file UIObject.h.

◆ IsUnique()

bool pcl::UIObject::IsUnique ( ) const

inline

Returns true iff the server-side object is uniquely referenced by this UIObject instance.

A uniquely referenced server-side object will be destroyed or recycled upon destruction of this UIObject.

Definition at line 143 of file UIObject.h.

◆ Null()

static UIObject& pcl::UIObject::Null ( )

static

Returns a reference to a null UIObject instance.

A null UIObject does not represent an existing object in the PixInsight core application.

◆ ObjectId()

String pcl::UIObject::ObjectId ( ) const

Returns the identifier of this UI object. The object identifier is a text string associated with the server-side UI object managed by this UIObject instance.

When this function is called for the first time for a given object, and no object identifier has been set explicitly in a previous call to SetObjectId(), a new identifier is generated automatically. In this case the generated object identifier is guaranteed to be unique across the entire PixInsight platform.

Object identifiers are useful to select individual instances. For example, an object identifier can be used to restrict the scope of an interface style sheet to a particular control. See the documentation for Control::SetStyleSheet() for more information.

See also: SetObjectId()

◆ ObjectType()

IsoString pcl::UIObject::ObjectType ( ) const

Returns a string that uniquely identifies the type of the server-side UI object managed by this UIObject.

◆ operator<()

bool pcl::UIObject::operator< ( const UIObject & o ) const

inline

Returns true iff this UIObject instance precedes another UIObject o. Performs a comparison based on the low-level handle internally maintained by each UIObject.

This member function is actually intended for fast access to large sets of UIObject instances stored in containers (as for example the whole set of user interface objects defined in a module). It is seldom used explicitly by modules.

Definition at line 237 of file UIObject.h.

◆ operator=() [1/2]

UIObject& pcl::UIObject::operator= ( const UIObject & x )

inlineprotected

Copy assignment operator. Returns a reference to this object.

Definition at line 315 of file UIObject.h.

◆ operator=() [2/2]

UIObject& pcl::UIObject::operator= ( UIObject && x )

inlineprotected

Move assignment operator. Returns a reference to this object.

Definition at line 324 of file UIObject.h.

◆ operator==()

bool pcl::UIObject::operator== ( const UIObject & o ) const

inline

A convenience synonym for IsSameObject( o ).

Definition at line 222 of file UIObject.h.

◆ RefCount()

size_type pcl::UIObject::RefCount ( ) const

Returns the total number of existing references to the server-side object managed by this UIObject.

The returned value is the sum of all references to the server-side object on the whole PixInsight platform, including all installed modules and the PixInsight core application.

◆ SetObjectId()

void pcl::UIObject::SetObjectId ( const String & id )

Sets the identifier of this UI object. Forcing an object identifier can be useful to select one or more controls for CSS styling with the Control::SetStyleSheet() member function. See the documentation for ObjectId() for more information.

See also: ObjectId()

The documentation for this class was generated from the following file:

UIObject.h

Public Member Functions

Static Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ ~UIObject()

◆ UIObject() [1/3]

◆ UIObject() [2/3]

◆ UIObject() [3/3]

Member Function Documentation

◆ EnsureUnique()

◆ IsAlias()

◆ IsGarbage()

◆ IsNull()

◆ IsSameObject()

◆ IsUnique()

◆ Null()

◆ ObjectId()

◆ ObjectType()

◆ operator<()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ operator==()

◆ RefCount()

◆ SetObjectId()