Basebutton

A basebutton is a view that encapsulates the basic event mechanisms of a button (onclick, onmousedown, onmouseover).

There are no visual elements to a basebutton so it requires a multi-frame resource to work correctly.

The example below shows how to construct a basebutton and how to respond to its events.

<canvas height="150">
  <!-- first create the multi-frame resource and give it a name -->
  <resource name="mybutton_rsrc">
   <!-- first frame MUST be the mouseup state of the button -->  
    <frame src="images/basebutton/button-up.png"/>
    <!-- second frame MUST be the mouseover state of the button -->
    <frame src="images/basebutton/button-over.png"/>
    <!-- third frame MUST be the mousedown state of the button -->
    <frame src="images/basebutton/button-down.png"/>
  </resource>
  
  <!-- Second, assign the resource to a basebutton tag -->
  <basebutton resource="mybutton_rsrc"/>
</canvas>

Using the example above, the basebutton will appear initially on screen in the 'mouseup' state and it will respond to the mouse events by showing the correct images associated with each event. In order to have the button do more than just switch images, a script needs to be added. There are three basic approaches for creating scripts to be executed by a basebutton once it has been clicked, and these approaches are shown below.

<canvas>
  <resource name="mybutton_rsrc">
    <frame src="images/basebutton/button-up.png"/>
    <!-- first frame MUST be the mouseup state of the button -->     
    <frame src="images/basebutton/button-over.png"/>
    <!-- second frame MUST be the mouseover state of the button -->     
    <frame src="images/basebutton/button-down.png"/>
    <!-- third frame MUST be the mousedown state of the button -->     
  </resource>
  
  <!-- APPROACH 1: include a script in the event attribute, onclick -->
  <basebutton resource="mybutton_rsrc" onclick="this.animate('x', 100, 1000, true)"/>
  
  <!-- APPROACH 2: include a script in the onclick attribute that calls a method -->
  <basebutton resource="mybutton_rsrc" onclick="this.doMyMethod()">
    <method name="doMyMethod">
      this.animate('x', 100, 1000, true, {motion: 'easeout'}); 
      this.animate('x', -100, 1000, true, {motion: 'easein'}); 
    </method>
  </basebutton>
  
  
  <!-- APPROACH 3: have the handler respond to the onclick event directly -->
  <basebutton resource="mybutton_rsrc">
    <handlername="onclick">
      this.animate('x', 100, 1000, true, {motion: 'easeout'}); 
      this.animate('x', -100, 1000, true, {motion: 'easein'}); 
    </handler>
  </basebutton>
  
  <simplelayout axis="y" spacing="20"/>
</canvas>

You can also use these approaches to respond to the other mouse events as well, if there is a need to do more then just switch images.

Attributes
Name	Usage	Type (Tag)	Type (JS)	Default	Category
disabledResourceNumber	Tag only	number		4	final
	The resource for the disabled state, default: 4. Use 0 if the resource has at least 4 frames, but there is no disabled state.

downResourceNumber	Tag only	number		3	final
	The resource for the mouse down state, default: 3. Use 0 if the resources has at least 3 frames, but there is no down state.

maxframes	Tag only	number			final
	The maximum number of frames to use, defaults to the number of frames for the resource associated with this view. This is useful for a subclass that has no resource for this view. Default is the total frames of basebutton.

normalResourceNumber	Tag only	number		1	final
	The resource for the mouse up state, and initial state of the button. Default: 1.

onresourceviewcount	Tag & JS	expression	any		setter
	This event is sent when the resourceviewcount changes.

overResourceNumber	Tag only	number		2	final
	The resource for the mouse over state, default: 2. Use 0 if the resource has at least 2 frames, but there is no over state.

reference	Tag only	expression			final
	Where to send mouse events (the view that will be "clickable"), default: this.

resourceviewcount	Tag & JS	number	Number	0	setter
	The first 'n' subviews that will respond to mouseevents by changing the frame number of their resource.

respondtomouseout	Tag & JS	expression	any	true	setter
	If this button does not respond to onmouseout or onmousedragout events, set this flag to false. Default: true.

setResourceViewCount()
basebutton.setResourceViewCount(rvc)
Setter for attribute resourceviewcount.
Parameters
Name	Type	Desc
rvc	Number	the resource view count.

showDown()
basebutton.showDown(sd)
This function is called whenever the button's visible state should appear to be down.
Parameters
Name	Type	Desc
sd	Boolean	unused.

showOver()
basebutton.showOver(sd)
This function is called whenever the button's visible state should appear to be hilited to indicate that it can be clicked.
Parameters
Name	Type	Desc
sd	Boolean	unused.

showUp()
basebutton.showUp(sd)
This function is called whenever the button's visible state should appear to be up.
Parameters
Name	Type	Desc
sd	Boolean	unused.

<basebutton>

Methods

doSpaceDown()
basebutton.doSpaceDown()
When the space bar is down, basebutton shows its down state.

doSpaceUp()
basebutton.doSpaceUp()
When the space bar is up, basebutton shows its up state.