control.h

这是VCF框架的代码

	/**
	@delegate ControlModelChanged fires an ControlEvent.
	Fired by the control when the control's setViewModel is called. This event
	indicates that the control's model pointer has changed, and anyone interested in
	listening to the control's model should update accordingly.
	@event ControlEvent
	@eventtype Control::CONTROL_MODELCHANGED
	*/
	DELEGATE(ControlModelChanged);

	/**
	@delegate BeforeControlPainted fires an ControlEvent.
	Fired by the control just before the control's
	paint() method is called. This will only happen if the
	control's getAllowPaintNotification() returns true.	The
	ControlEvent's getPaintGraphicsContext() method will
	return the same GraphicsContext that passed to the
	control's paint() method.
	@event ControlEvent
	@eventtype Control::BEFORE_CONTROL_PAINTED
	*/
	DELEGATE(BeforeControlPainted);

	/**
	@delegate AfterControlPainted fires an ControlEvent.
	Fired by the control after the control's
	paint() method is called. This will only happen if the
	control's getAllowPaintNotification() returns true. The
	ControlEvent's getPaintGraphicsContext() method will
	return the same GraphicsContext that passed to the
	control's paint() method.
	@event ControlEvent
	@eventtype Control::AFTER_CONTROL_PAINTED
	*/
	DELEGATE(AfterControlPainted);

	/**
	@delegate AfterControlPainted fires an ControlPopupMenuMenuEvent
	before the popup menu is displayed, allowing for customization
	of the popup menu.
	@event ControlPopupMenuMenuEvent
	@eventtype Control::BEFORE_POPUP_MENU
	*/
	DELEGATE(BeforePopupMenu);
	
	

	/**
	This gets called by the ControlPeer for any windowing system mouse events,
	as well as for any windowing system keyboard events and for any
	windowing system events like size changes, position changes, etc.
	Once inside the event the Control determines the type, and behaves accordingly,
	as well as notifying any appropriate listeners.
	*/
	virtual void handleEvent( Event* event );

	/**
	calls handleEvent on this control, and then
	calls handleEventToChildren() on any child controls the
	container of this control may have.
	*/
	void handleEventAndForwardToChildren( Event* event );

	/**
	*Returns the control's current border object, if any
	*/
	Border* getBorder();

	/**
	\p
	Sets the border for this control. The control will check the
	border's owner value, and if it's NULL then it will set itself
	as the component owner of the border.
	*/
	void setBorder( Border* border );

	/**
	returns the bounds in parent coordinates of the Control. The Control derived class must call it's Peer's getBounds() method
	*/
	virtual Rect getBounds() ;/**throw( InvalidPeer ); -JEC - FIXME later*/

	/**
	Returns the bounds in terms of the control's coordinates. Thus the top and
	left will typically be 0.0, 0.0, and the right and bottom of the bounds
	will typically equal the width and height of the control.
	*/
	virtual Rect getClientBounds( const bool& includeBorder = true ) ;/**throw( InvalidPeer ); -JEC - FIXME later*/

	/**
	Returns the left position in parent coordinates
	*/
	virtual double getLeft() ;/**throw( InvalidPeer ); -JEC - FIXME later*/

	/**
	Returns the right position in parent coordinates
	*/
	virtual double getRight() ;

	/**
	*returns the width of the control
	*/
	virtual double getWidth() ;/**throw( InvalidPeer ); -JEC - FIXME later*/

	/**
	*returns the top position in parent coordinates
	*/
	virtual double getTop() ;/**throw( InvalidPeer ); -JEC - FIXME later*/

	/**
	*returns the bottom position in parent coordinates
	*/
	virtual double getBottom() ;

	/**
	*returns the height of the control
	*/
	virtual double getHeight() ;/**throw( InvalidPeer ); -JEC - FIXME later*/

	/**
	*is this control visible to the user.
	*@return bool true if the control is visible, otherwise
	*false.
	*/
	virtual bool getVisible() ;/**throw( InvalidPeer ); -JEC - FIXME later*/

	/**
	\p
	Returns the control's alignment. These alignment values are used by
	the basic container type, the StandardContainer class, which uses these
	values to determine how to layout the controls. Other layout implementations
	may choose to ignore these values. For example, the HorizontalLayoutContainer
	doesn't pay any attention to these value, it just lays out the controls
	as they are added.
	@see isIgnoredForLayout()
	@see setIgnoredForLayout()
	*/
	AlignmentType getAlignment();

	/**
	\p
	Returns whether this control must be ignored in the control container's
	layout implementation. Unlike the alignment values returned by getAlignment(),
	which are optional for the container to use, this \em must be honored.
	Failure to do so may result in dire intergalatic consequences, or
	worse, result in a shortage of SUVs.
	\p
	If this is false, the default value, then the control is laid out however the
	container is implemented to accomplish this. If the value is true, then the
	container should simply place the control wherever the controls bounds
	indicate. Container implementations that have some sort of layout that processes
	controls sequentially, such as the HorizontalLayoutContainer, \em must
	ignore a control that returns false.
	*/
	bool isIgnoredForLayout();

	void setIgnoredForLayout( const bool& val );

	/**
	sets the bounds of the control. You can pass in left, top, width and height as the
	new position for the control.
	@param double x the new left coordinate of the control
	@param double y the new top coordinate of the control
	@param double width the new width of the control
	@param double height the new height of the control
	*/
	void setBounds( const double& x, const double& y, const double& width, const double& height );

	/**
	*sets the bounds of the control. The values in the rect parameter must be
	*in the corrdinate system of the parent control
	*@param Rect the new bounds of the control. If the control
	*implements the Container interface, then any child controls
	*wil be resized via the Container::resizeChildren() automatically.
	*/
	virtual void setBounds( Rect* rect, const bool& anchorDeltasNeedUpdating=true ) ;/**throw( InvalidPeer ); -JEC - FIXME later*/

	/**
	*sets the alignment of the control
	*/
	void setAlignment( const AlignmentType& alignment );

	/**
	*sets the left value for the control, immediately updates the
	*controls position.
	*/
	virtual void setLeft( const double& left ) ;/**throw( InvalidPeer ); -JEC - FIXME later*/

	/**
	*sets the right value of the control. This value is in the
	*coordinates of the parent control.
	*/
	virtual void setRight( const double& right ) ;

	/**
	*sets the width of the control.
	*If the control implements the Container interface,
	*then any child controls will be resized via the
	*Container::resizeChildren() automatically.
	*/
	virtual void setWidth( const double& width ) ;/**throw( InvalidPeer ); -JEC - FIXME later*/

	/**
	*sets the top value of the control. This value is in the
	*coordinates of the parent control.
	*/
	virtual void setTop( const double& top ) ;/**throw( InvalidPeer ); -JEC - FIXME later*/

	/**
	*sets the bottom value of the control. This value is in the
	*coordinates of the parent control.
	*/
	virtual void setBottom( const double& bottom ) ;

	/**
	*sets the height of the control.
	*If the control implements the Container interface,
	*then any child controls will be resized via the
	*Container::resizeChildren() automatically.
	*/
	virtual void setHeight( const double& height ) ;/**throw( InvalidPeer ); -JEC - FIXME later*/

	/**
	*determines whether or not the control is visible,
	* and set it visible if it wasn't.
	*@param bool true to show the control, false to hide it
	*/
	virtual void setVisible( const bool& visible ) ;/**throw( InvalidPeer ); -JEC - FIXME later*/


	/**
	*if autoStartDragDrop_ is true then this method checks to see if
	*the Controls dragging is with the windowing system's tolernace
	*for a drag drop operation to start. other wise it returns false.
	*If  autoStartDragDrop_ is false then it returns false unless some
	*derived class overides the functionality.
	*/
	virtual bool canBeginDragDrop( Point* point );

	/**
	*sets auto start dragging to true or false
	*/
	void setAutoStartDragDrop(const bool& canAutoStartDragDrop);

	/**
	*returns whether or not auto dragging is on or off.
	*@return bool true if auto dragging is on, otherwise false.
	*/
	bool getAutoStartDragDrop();

	/**
	*Override this to provide functionality for handling the
	*start of drag-drop operation
	*This will get called automatically by the framework if it
	*detects that a mouse-move has occured that indicates a
	*drag-drop operation COULD occur.
	*@return bool must return true if a drag-drop operation
	*was started, otherwise should return false
	*/
	virtual bool beginDragDrop( MouseEvent* event );

	/**
	*returns the control's native peer interface
	*/
	virtual ControlPeer* getPeer();

	/**
	*sets the parent for the control
	*/
	virtual void setParent( Control* parent ) ;/**throw( InvalidPeer ); -JEC - FIXME later*/

	/**
	*returns the control's current parent
	*/
	virtual Control* getParent() ;/**throw( InvalidPeer ); -JEC - FIXME later*/


	void removeFromParent( const bool& freeInstance=true );

	/**
	*does this control currently have focus?
	*@return bool true if the control has focus, otehr wise false. If a control
	*has focus, it will receive keyboard events. Currently all controls
	*get focused when they receive a mouse down event.
	*/
	bool isFocused();

	/**
	Makes this control the currently focused control. A control with focus
	will receive keyboard events.
	@return Control - the previously focused control (which will receive a
	FocusLost event).
	*/
	Control* setFocused();

	/**
	*returns whether the control is enabled or not. A control that is
	*enabled can receive mouse events. A control that is not enabled
	*will not respond to either mouse events or keyboard events.
	*/
	bool isEnabled();

	/**
	This checks not only to see if the control itself is
	enabled, but will return false if any parent control is
	not enabled. This function traverse all the parent child
	relationships till the frame window is hit, and checks the
	enabled status of each control. The first control that is
	\em not enabled stops the search and the methods returns
	false, otherwise it continues till it finds a NULL
	parent and returns true.
	*/
	bool areParentsEnabled();

	/**
	*sets whether the control is enabled or not.
	*@param bool true if the control is enabled, otherwise false.
	*/
	void setEnabled( const bool& enabled );

	/**
	
	Paints the control. Called by the underlying windowing system whenever
	the control needs to be painted. Note that in some cases the GraphicsContext
	passed in to this method may not be the same pointer as the GraphicsContext
	that the control holds itself. During the paint() method you should only
	use the context value for all your drawing and not the one returned in
	getContext(). The value returned by getContext() should be used for drawing
	that takes place outside of the paint() method.
	
	If the control allows paint notification, then the framework will fire an 
	event to the BeforeControlPainted delegate \em prior to calling the 
	control's paint() method. After the paint() method has returned, if
	the control allows paint notification, the framework will fire an event to
	the AfterControlPainted delegate. This allows outside observers to take 
	part in the paint cycle, \em but beware that this does come at a bit of a 
	cost, so use this feature sparingly.
	
	\em Note: This should \em NEVER be called
	by programmers using the VCF, it will be called for you during the course 
	of your applications native event loop, and is only here for providing 
	custom drawing routines for controls. In other words: you implement it, 
	you never call it yourself.
	@see getAllowPaintNotification
	*/
	virtual void paint( GraphicsContext * context )=0;

	/**
	Paints the border for the control. This is called by the framework during the
	painting of the control. Do not count on this being called at the same time as the
	paint() method, as the order in which this is called is dependant on the
	underlying windowing system. For example, on Win32 systems this call may
	be made by the framework outside of the WM_PAINT message handling, while on
	Mac OS X this will be called in the same event handler that dispatches
	the control's paint() method.
	*/
	void paintBorder( GraphicsContext * context );
	/**
	*Called when the mouse first enters the control's bounds.
	*override this to provide specific behaviours when the control is
	*first entered, like highlighting the control
	*/
	virtual void mouseEnter( MouseEvent* event );

	/**
	*Called when one (or more) of the mouse buttons are held down.
	*override this to provide specific behaviours when
	*the mouse buttons are held down
	*/
	virtual void mouseDown( MouseEvent* event );

	/**
	*Called when the mouse moves over the control.
	*override this to provide specific behaviours when
	*the mouse moves over the control.
	*/
	virtual void mouseMove( MouseEvent* event );

	/**
	*Called when one (or more) of the mouse buttons are released.
	*override this to provide specific behaviours when
	*the mouse buttons are released.
	*/
	virtual void mouseUp( MouseEvent* event );

	/**
	*Called when one or mouse buttons are held down and
	*immediately released ( a "mouse click" ).
	**override this to provide specific behaviours when
	*a mouse click occurs
	*/
	virtual void mouseClick(  MouseEvent* event );

	/**
	*Called when one or mouse buttons are held down and
	*immediately released ( a "mouse double click" ) twice, within
	*some specific time period, as determined on the windowing
	*system.
	**override this to provide specific behaviours when
	*a mouse double click occurs
	*/
	virtual void mouseDblClick(  MouseEvent* event );

	/**
	*Called when the mouse leaves the control's bounds.
	*override this to provide specific behaviours when the control is
	*left, like highlighting the control
	*/
	virtual void mouseLeave( MouseEvent* event );

	/**
	*called when the user presses the key down
	*/
	virtual void keyDown( KeyboardEvent* event );

	/**
	*called when the user simply presses the key and represents a
	*full key cycle having occurred, in other words the key has been
	*pressed down and then released
	*/
	virtual void keyPressed( KeyboardEvent* event );

	/**
	*called when the user releases the key
	*/
	virtual void keyUp( KeyboardEvent* event );

	/**
	called when the control's bounds change. Override this
	for your own custom behaviour if you need to.
	*/
	virtual void sizeChange( ControlEvent* event );

	/**
	called when the control's coordinates change. Override this
	for your own custom behaviour if you need to.
	*/
	virtual void positionChange( ControlEvent* event );

	/**
	Called when the parent of the control is changed. Override this
	for your own custom behaviour if you need to.
	*/
	virtual void parentChange( ControlEvent* event );

	/**
	Called when the control gains keyboard focus. Override this
	for your own custom behaviour if you need to.
	*/
	virtual void gotFocus( FocusEvent* event );

	/**
	Called when the control loses keyboard focus. Override this
	for your own custom behaviour if you need to.
	*/
	virtual void lostFocus( FocusEvent* event );