Class: TPlayerControl

Declaration: PlayerControls.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

TSimpleView

Inherited By:

None.

Purpose:

The TimeMedia UI framework provides a set of player controls. These player controls are visible as a control panel on the view display. There are controls for various player functions, such as play, pause, seek, and so on. The developer can create a custom control panel by adding sliders and buttons into the control panel. TPlayerControl is a convenience class that provides a default player control panel. This default panel includes a set of standard controls, such as the play, record, and pause buttons. There is also a seek slider for random seeking and a volume slider to control the volume. The control panel layout resembles that of the QuickTime player controls. TPlayerControl is adopted by the media view as a child view.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

None.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Other Considerations:

None.

Member Function: TPlayerControl::CreateClockGraphic

static TGraphicLabel * CreateClockGraphic(const TAllocationHeap & thisHeap, GCoordinate width =kButtonGraphicWidth, GCoordinate height =kButtonGraphicHeight)

Interface Category:

API.

Purpose:

Creates a clock graphic for allowing the user to control the media presentation clock.

Calling Context:

Call this function directly.

Parameters:

const TAllocationHeap & thisHeap -The heap location from which memory is allocated.
GCoordinate width =kButtonGraphicWidth -The width of the clock graphic.
GCoordinate height =kButtonGraphicHeight -The height of the clock graphic .

Return Value:

Returns a pointer to a TGraphicLabel object that locates the clock within the view.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPlayerControl::CreateVolumeGraphic

static TGraphicLabel * CreateVolumeGraphic (const TAllocationHeap & thisHeap, GCoordinate width =kButtonGraphicWidth * 0.67, GCoordinate height =kButtonGraphicHeight * 0.84)

Interface Category:

API.

Purpose:

Creates a volume slider graphic for allowing the user to control the media presentation volume.

Calling Context:

Call this function directly.

Parameters:

const TAllocationHeap & thisHeap -The heap location from which memory is allocated.
GCoordinate width =kButtonGraphicWidth * 0.67 -The width of the volume slider graphic.
GCoordinate height =kButtonGraphicHeight * 0.84 -The height of the volume slider graphic.

Return Value:

Returns a pointer to a TGraphicLabel object that locates the volume slider within the view.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPlayerControl::CreatePlayGraphic

static TGraphicLabel * CreatePlayGraphic (const TAllocationHeap & thisHeap, GCoordinate width =kButtonGraphicWidth * 0.56, GCoordinate height =kButtonGraphicHeight * 0.75)

Interface Category:

API.

Purpose:

Creates a Play button graphic control within the view that allows the user to start playing the media presentation.

Calling Context:

Call this function directly.

Parameters:

const TAllocationHeap & thisHeap -The heap location from which memory is allocated for the Play button graphic.
GCoordinate width =kButtonGraphicWidth * 0.56 -The width of the Play button graphic.
GCoordinate height =kButtonGraphicHeight * 0.75 -The height of the Play button graphic.

Return Value:

Returns a pointer to a TGraphicLabel object that references the Play button graphic within the view.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPlayerControl::CreateStopGraphic

static TGraphicLabel * CreateStopGraphic (const TAllocationHeap & thisHeap, GCoordinate width =kButtonGraphicWidth * 0.78, GCoordinate height =kButtonGraphicHeight * 0.59)

Interface Category:

API.

Purpose:

Creates a Stop button graphic control within the view that allows the user to stop playing the media presentation.

Calling Context:

Call this function directly.

Parameters:

const TAllocationHeap & thisHeap -The heap location from which memory is allocated for the Stop button graphic.
GCoordinate width =kButtonGraphicWidth * 0.78 -The width of the Stop button graphic.
GCoordinate height =kButtonGraphicHeight * 0.59 -The height of the Stop button graphic.

Return Value:

Returns a pointer to a TGraphicLabel object that references the stop button graphic within the view.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPlayerControl::CreateRecordGraphic

static TGraphicLabel * CreateRecordGraphic (const TAllocationHeap & thisHeap, GCoordinate width =kButtonGraphicWidth * 0.78, GCoordinate height =kButtonGraphicHeight * 0.59)

Interface Category:

API.

Purpose:

Creates a Record button graphic control within the view that allows the user to start recording the media.

Calling Context:

Call this function directly.

Parameters:

const TAllocationHeap & thisHeap -The heap location from which memory is allocated for the Record button graphic.
GCoordinate width =kButtonGraphicWidth * 0.78 -The width of the Record button graphic.
GCoordinate height =kButtonGraphicHeight * 0.59 -The height of the Record button graphic.

Return Value:

Returns a pointer to a TGraphicLabel object that references the Record button graphic within the view.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPlayerControl::CreateStepForwardGraphic

static TGraphicLabel * CreateStepForwardGraphic (const TAllocationHeap & thisHeap, GCoordinate width =kButtonGraphicWidth, GCoordinate height =kButtonGraphicHeight * 0.75)

Interface Category:

API.

Purpose:

Creates a Step Forward button graphic control within the view that allows the user to fast forward through the media. This button is not part of the default control panel as it does not apply to all media types; it can be added when appropriate using the adopt member functions.

Calling Context:

Call this function directly.

Parameters:

const TAllocationHeap & thisHeap -The heap location from which memory is allocated for the Step Forward button graphic.
GCoordinate width =kButtonGraphicWidth -The width of the Step Forward button graphic.
GCoordinate height =kButtonGraphicHeight * 0.75 -The height of the Step Forward button graphic.

Return Value:

Returns a pointer to a TGraphicLabel object that references the Step Forward button graphic within the view.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPlayerControl::CreateStepBackwardGraphic

static TGraphicLabel * CreateStepBackwardGraphic (const TAllocationHeap & thisHeap, GCoordinate width =kButtonGraphicWidth, GCoordinate height =kButtonGraphicHeight * 0.75)

Interface Category:

API.

Purpose:

Creates a Step Backward button graphic control within the view that allows the user to rewind through the media. This button is not part of the default control panel as it does not apply to all media types; it can be added when appropriate using the adopt member functions.

Calling Context:

Call this function directly.

Parameters:

const TAllocationHeap & thisHeap -The heap location from which memory is allocated for the Step Backward button graphic.
GCoordinate width =kButtonGraphicWidth -The width of the Step Backward button graphic.
GCoordinate height =kButtonGraphicHeight * 0.75 -The height of the Step Backward button graphic.

Return Value:

Returns a pointer to a TGraphicLabel object that references the Step Backward button graphic within the view.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPlayerControl::TPlayerControl

TPlayerControl (TPresenterReference & reference, bool hasVolumeControl =true, bool hasStepControls =false)
TPlayerControl ()

Interface Category:

API.

Purpose:

Normal constructor for creating the player control panel.
Default constructor.

Calling Context:

Called to create a player control panel.
Called by the stream-in operators and to create the default player control panel.

Parameters:

TPresenterReference & reference -A reference to the media presenter object.
bool hasVolumeControl =true -Indicates whether the player control panel has a volume control; by default, it has one.
bool hasStepControls =false -Indicates whether the player control panel has step controls; by default, it doesn't.
Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPlayerControl::~TPlayerControl

virtual ~ TPlayerControl ()

Interface Category:

API.

Purpose:

Destructor.

Calling Context:

Called to destroy an object.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPlayerControl::Hash

virtual long Hash () const

Interface Category:

API.

Purpose:

Returns the hash value that uniquely identifies this object within its type. Hash values are used to build dictionaries of objects.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns the hash value that uniquely identifies this object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPlayerControl::operator==

bool operator ==(const TPlayerControl &) const

Interface Category:

API.

Purpose:

Tests for equality between the argument and itself.

Calling Context:

Called directly to see if two player controls are the same.

Parameters:

const TPlayerControl & -Specifies the player control to compare with.

Return Value:

Returns true if the passed-in player control is the same as itself; otherwise, it returns false.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPlayerControl::operator!=

bool operator != (const TPlayerControl &) const

Interface Category:

API.

Purpose:

Tests for inequality between the argument and itself.

Calling Context:

Called directly to see if two player controls are different.

Parameters:

const TPlayerControl & -Specifies the player control to compare with.

Return Value:

Returns true if the passed-in player control is different from itself; otherwise, it returns false.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPlayerControl::operator>>=

virtual TStream & operator >>=(TStream &) const

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

Called to stream out data.

Parameters:

TStream & -The stream the object streams itself out to.

Return Value:

Returns a reference to the stream the object streams itself out to.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPlayerControl::operator<<=

virtual TStream & operator <<= (TStream &)

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Called to stream in data.

Parameters:

TStream & -The stream the object streams itself in from.

Return Value:

Returns a reference to the stream the object streams itself in from.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPlayerControl::UsePlayLabel

virtual void UsePlayLabel (bool flag =true)

Interface Category:

API.

Purpose:

Toggles between the Play and Pause graphic labels for the play/pause button.

Calling Context:

Call this function directly.

Parameters:

bool flag =true -Sets the flag value to true, which means the Play button is functional for this control panel.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPlayerControl::UseRecordLabel

virtual void UseRecordLabel (bool flag =true)

Interface Category:

API.

Purpose:

Toggles between the Record and Pause graphic labels for the record/pause button.

Calling Context:

Call this function directly.

Parameters:

bool flag =true -Sets the flag value to true, which means the Record button is in use for this control panel.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPlayerControl::SetRecordEnabled

virtual void SetRecordEnabled (bool)

Interface Category:

API.

Purpose:

Toggles the state of the Record button. If set to true, it enables the record button. If set to false, it disables the record button.

Calling Context:

Call this function directly.

Parameters:

bool -Sets the state of the Record button to either true or false.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPlayerControl::SetHasVolumeControls

virtual void SetHasVolumeControls (bool)

Interface Category:

API.

Purpose:

Sets up this control panel as having a volume control.

Calling Context:

Call this function directly.

Parameters:

bool -A Boolean value of true or false.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPlayerControl::SetHasStepControls

virtual void SetHasStepControls (bool)

Interface Category:

API.

Purpose:

Sets up this control panel as having step controls.

Calling Context:

Call this function directly.

Parameters:

bool -A Boolean value of true or false.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPlayerControl::SetPresenter

virtual void SetPresenter (const TPresenterReference & reference)

Interface Category:

API.

Purpose:

Sets the presenter object to be used by this player control panel.

Calling Context:

Call this function directly.

Parameters:

const TPresenterReference & reference -A reference to the TPresenterReference object that defines the semantics for this control panel.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPlayerControl::AdoptSliderControl

virtual void AdoptSliderControl (TSliderControl *)

Interface Category:

API.

Purpose:

Allows a new slider control to be added to the control panel. This function is used for customizing the player control panel.

Calling Context:

Called directly to add a new slider control.

Parameters:

TSliderControl * -A pointer to the slider control to be added to the control panel.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPlayerControl::AdoptMomentaryControl

virtual void AdoptMomentaryControl (TMomentaryControl *)

Interface Category:

API.

Purpose:

Selects the momentary action control state. When momentary control is selected, button actions initiated by users are generated. This carries out the control button action that was selected by the user.

Calling Context:

Call this function directly.

Parameters:

TMomentaryControl * -A pointer to the momentary control object for carrying out the button action.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPlayerControl::Initialize

virtual void Initialize ()

Interface Category:

API.

Purpose:

Sets up all the control elements for the player control panel.

Calling Context:

This function is protected and should not be called directly by clients.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPlayerControl::CreateVolumeControl

TMenu * CreateVolumeControl () const

Interface Category:

API.

Purpose:

Creates a volume control.

Calling Context:

Called by Initialize. This function is protected and should not be called directly by clients.

Parameters:

Takes no parameters.

Return Value:

Returns a pointer to the TMenu object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPlayerControl::CreateButton

TPushButton * CreateButton (TLabel * labelToAdopt) const

Interface Category:

API.

Purpose:

Creates a button with the appropriate graphic label.

Calling Context:

Called by Initialize. This function is protected and should not be called directly by clients.

Parameters:

TLabel * labelToAdopt -A pointer to the TLabel object that contains the label for this button.

Return Value:

Returns a pointer to the button object that becomes part of the control panel.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPlayerControl::CreateSlider

TLineSlider * CreateSlider () const

Interface Category:

API.

Purpose:

Creates a seek slider.

Calling Context:

Called by Initialize. This function is protected and should not be called directly by clients.

Parameters:

Takes no parameters.

Return Value:

Returns a pointer to the TLineSlider object that is created for the control panel display.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPlayerControl::HandleAllocatedAreaChanged

virtual void HandleAllocatedAreaChanged (const TGArea &)

Interface Category:

API.

Purpose:

Handles a change to the allocated area for the control panel view.

Calling Context:

Called when there is a change to the allocated area of the control panel child view. Derived classes can override this member function when they want to know when things have changed. The derived function should call the base class version at some point during its execution.

Parameters:

const TGArea & -A reference to the new TGArea object.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function is called outside of the scope of the view hierarchy lock.

Member Function: TPlayerControl::CreateView

TLabelView * CreateView (TLabel * labelToAdopt) const

Interface Category:

API.

Purpose:

Creates and returns a view containing a clock graphic.

Calling Context:

Currently only called by Initialize during construction.

Parameters:

TLabel * labelToAdopt -Specifies a Clock graphic label.

Return Value:

Returns a pointer to a TLabelView.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPlayerControl::CreatePauseGraphic

static TGraphicLabel * CreatePauseGraphic (const TAllocationHeap & thisHeap, GCoordinate width =kButtonGraphicWidth * 0.89, GCoordinate height =kButtonGraphicHeight * 0.59)

Interface Category:

API.

Purpose:

Creates a Pause graphic button graphic control within the view that allow the user to pause. This button is not part of the default control panel as it does not apply to all media types; it can be added when appropriate using the Adopt member function.

Calling Context:

Call this function directly.

Parameters:

const TAllocationHeap & thisHeap -The heap location from which memory is allocated for the Pause graphic button graphic.
GCoordinate width =kButtonGraphicWidth * 0.89 -The width of the Pause button graphic.
GCoordinate height =kButtonGraphicHeight * 0.59 -The height of the Pause button graphic.

Return Value:

Returns a pointer to a TGraphicLabel object that references the Pause button graphic within the view.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Click the icon to mail questions or corrections about this material to Taligent personnel.