Mouse Actions:
In order to keep track of the current state of the mouse, /mouse_action datums have been created. Mouse actions are unique datums that track the mouse state from hover until the mouse is pressed and released. A new mouse action is created only after client.MouseUp() is called, thus completing a specific mouse action.
client.mouse_action
The current mouse action is stored on the client in the mouse_action variable. This variable is only valid for the duration of the current mouse action. There will always be a current mouse_action for the duration of the client's lifetime.
Mouse actions have two variables:
data
state
/mouse_action.state is an integer value that will be one of the following values:
MOUSE_HOVER (0)
MOUSE_HOLD (1)
MOUSE_RELEASE (2)
MOUSE_DRAG (3)
MOUSE_DROP (4)
When a mouse action has never had a mouse button held during its lifetime, it will be in the state MOUSE_HOVER.
When a button has been pressed, but the mouse has not been dragged, the state of the mouse action is MOUSE_HOLD.
If the mouse is released before a drag action starts, the state of the mouse action is MOUSE_RELEASE. The mouse actions state is set to MOUSE_RELEASE after MouseUp() is called, but before a new mouse action replaces the current one on the client.
Once MouseDragStart() has been called, the state of the mouse action is set to MOUSE_DRAG.
Once MouseDrop() or certain MouseUp() actions are called, the state of the mouse action is set to MOUSE_DROP prior to the creation of a new mouse_action to replace the current one.
/mouse_action.data should not be accessed directly unless you wish to override mouse actions to create new behavior. This is not currently recommended or supported. It is recommended to access this data by indexing the mouse action directly as though the datum were a list.
The following properties are recognized by default:
src-object or object or start-object
src-location or location or start-location
src-control or control or start-control
src-params or params or start-params
over-object or end-object
over-location or end-location
over-control or end-control
over-params or end-params
Accessing the properties of a mouse action is simple:
if(mouse_action["src-object"]==src)
//do something
You can also get the state of a mouse object using the same indexing:
world.log << mouse_action["state"]
world.log << mouse_action.state
You can also set the variables of a mouse action, and store additional data in a similar manner:
mouse_action["state"] = MOUSE_DRAG
mouse_action["src-object"] = src
mouse_action["tempdata"] = usr
Note that the temporary data is only valid for the lifetime of the mouse action. If you need to do something with a mouse action over time, be sure to store the mouse action you want to use, as the client will discard it immediately when a new action takes precedence after the next MouseUp() call.
This library has completely overridden how mouse params work by wrapping the param strings in a datum that makes them easier to work with and takes out a lot of the boilerplate required to work with mouse param strings.
If you want to plug this library into an existing project that handles the param variable of mouse procs as strings, you should define PARAMS2LIST_OVERRIDE prior to including the library in your project. This will implement a safety check that allows all future uses of paramstrings to disambiguate between a mouse_params datum and a param string. This will allow your existing code to continue to work properly while you adapt your code to the new approach. Be aware that this adds a very small amount of overhead to every params2list() call globally, so it should only be a temporary measure to allow proper integration of this library.
By default, this library wraps the params argument of all mouse procs in a mouse_params datum. This datum is not parsed until data is requested from it. Be aware that this means that any overrides to client mouse procs that are compiled after the inclusion of this library will not have their parameters overridden, so it is best to include this library at the end of your project's DME.
The mouse_params datum can be accessed like a list using indexing similarly to mouse actions. The following params are valid:
params returns the full param string
params-list returns the param string as a list
icon-pos returns icon-x and icon-y as a list of numbers
icon-x returns icon-x as a number
icon-y returns icon-y as a number
icon-loc returns icon-x and icon-y as a comma-separated string
screen-loc returns the screen-loc as a string
screen-pos returns a parsed list in screen_loc format
screen-x returns a numeric screen x value
screen-y returns a numeric screen y value
screen-control returns the id of the control from screen-loc as text
vis-pos returns a list of vis-x and vis-y in numeric format
vis-x returns vis-x in numeric format
vis-y returns vis-y in numeric format
vis-loc returns vis-x and vis-y as a comma-separated string
buttons returns bitflags that correspond to which modifiers and keys are held
left returns true as a string if left is pressed
middle returns true as a string if middle is pressed
right returns true as a string if right is pressed
shift returns true as a string if shift is pressed
ctrl returns true as a string if ctrl is pressed
alt returns true as a string if alt is pressed
drag-cell returns the cell a drag action started in
drop-cell returns the cell a drop action started in
drag returns the button used to initiate a drag action
link returns the link pressed in maptext
Mouse flags:
MOUSE_BUTTON1 (1)
MOUSE_BUTTON2 (2)
MOUSE_BUTTON3 (4)
MOUSE_SHIFT (8)
MOUSE_CTRL (16)
MOUSE_ALT (32)
When getting the buttons parameter from mouse_params, use these values can be used to test which mouse modifiers and buttons are pressed.
Screen loc format:
list(screen-x as num,screen-y as num,control as text|null)
Utility functions:
parse_screen_loc("C:TX:PX,TY:PY"): returns a screen-loc format list
parse_size("WxH"): returns a list of numbers
parse_pos("X,Y"): returns a list of numbers
Temporary data:
Temporary data can be stored similarly to how it is stored in mouse_actions. This data will only persist until the parameter is no longer referenced, and is preferred for shorter term information storage.