summaryrefslogtreecommitdiff
path: root/src/lib/evas/Evas.h
diff options
context:
space:
mode:
authorCarsten Haitzler (Rasterman) <raster@rasterman.com>2013-04-12 20:04:34 +0900
committerCarsten Haitzler (Rasterman) <raster@rasterman.com>2013-04-12 20:05:16 +0900
commit9b0e7626f40b56d33af233053a6a3bb3dcf5bb70 (patch)
treefaecc4898a78300867ed7ce1154c2e846b1e0210 /src/lib/evas/Evas.h
parent3e11c380c946464360f18b058afca783cde3ddde (diff)
Add subclasses for evas device api (new in 1.8) and document the evas
device api... :)
Diffstat (limited to 'src/lib/evas/Evas.h')
-rw-r--r--src/lib/evas/Evas.h201
1 files changed, 199 insertions, 2 deletions
diff --git a/src/lib/evas/Evas.h b/src/lib/evas/Evas.h
index 33bcfcc893..9dcbfdaea4 100644
--- a/src/lib/evas/Evas.h
+++ b/src/lib/evas/Evas.h
@@ -1002,8 +1002,23 @@ typedef enum _Evas_Device_Class
1002 EVAS_DEVICE_CLASS_PEN, /**< A special pen device @since 1.8 */ 1002 EVAS_DEVICE_CLASS_PEN, /**< A special pen device @since 1.8 */
1003 EVAS_DEVICE_CLASS_POINTER, /**< A laser pointer, wii-style or "minority report" pointing device @since 1.8 */ 1003 EVAS_DEVICE_CLASS_POINTER, /**< A laser pointer, wii-style or "minority report" pointing device @since 1.8 */
1004 EVAS_DEVICE_CLASS_GAMEPAD /**< A gamepad controller or joystick @since 1.8 */ 1004 EVAS_DEVICE_CLASS_GAMEPAD /**< A gamepad controller or joystick @since 1.8 */
1005} Evas_Device_Class; 1005} Evas_Device_Class; /**< A general class of device @since 1.8 */
1006 1006
1007typedef enum _Evas_Device_Subclass
1008{
1009 EVAS_DEVICE_SUBCLASS_NONE, /**< Not a device @since 1.8 */
1010 EVAS_DEVICE_SUBCLASS_FINGER, /**< The normal flat of your finger @since 1.8 */
1011 EVAS_DEVICE_SUBCLASS_FINGERNAIL, /**< A fingernail @since 1.8 */
1012 EVAS_DEVICE_SUBCLASS_KNUCKLE, /**< A Knuckle @since 1.8 */
1013 EVAS_DEVICE_SUBCLASS_PALM, /**< The palm of a users hand @since 1.8 */
1014 EVAS_DEVICE_SUBCLASS_HAND_SIZE, /**< The side of your hand @since 1.8 */
1015 EVAS_DEVICE_SUBCLASS_HAND_FLAT, /**< The flat of your hand @since 1.8 */
1016 EVAS_DEVICE_SUBCLASS_PEN_TIP, /**< The tip of a pen @since 1.8 */
1017 EVAS_DEVICE_SUBCLASS_TRACKPAD, /**< A trackpad style mouse @since 1.8 */
1018 EVAS_DEVICE_SUBCLASS_TRACKPOINT, /**< A trackpoint style mouse @since 1.8 */
1019 EVAS_DEVICE_SUBCLASS_TRACKBALL, /**< A trackball style mouse @since 1.8 */
1020} Evas_Device_Subclass; /**< A general class of device @since 1.8 */
1021
1007struct _Evas_Engine_Info /** Generic engine information. Generic info is useless */ 1022struct _Evas_Engine_Info /** Generic engine information. Generic info is useless */
1008{ 1023{
1009 int magic; /**< Magic number */ 1024 int magic; /**< Magic number */
@@ -4105,76 +4120,258 @@ EAPI void evas_event_thaw_eval(Evas *e) EINA_ARG_NONNULL(1);
4105 */ 4120 */
4106 4121
4107/** 4122/**
4123 * Add a new device type
4124 *
4125 * @param e The canvas to create the device node for.
4126 *
4127 * Adds a new device nod to the given canvas @p e. All devices created as
4128 * part of the canvas @p e will automatically be deleted when the canvas
4129 * is freed.
4130 *
4131 * @see evas_device_del
4108 * @since 1.8 4132 * @since 1.8
4109 */ 4133 */
4110EAPI Evas_Device *evas_device_add(Evas *e); 4134EAPI Evas_Device *evas_device_add(Evas *e);
4111 4135
4112/** 4136/**
4137 * Delete a new device type
4138 *
4139 * @see evas_device_add
4140 * @see evas_device_push
4141 * @see evas_device_pop
4113 * @since 1.8 4142 * @since 1.8
4114 */ 4143 */
4115EAPI void evas_device_del(Evas_Device *dev); 4144EAPI void evas_device_del(Evas_Device *dev);
4116 4145
4117/** 4146/**
4147 * Push the current context device onto the device stack
4148 *
4149 * @param e The canvas to push the device on to
4150 * @param dev The device to push.
4151 *
4152 * This pushes the given device @p dev onto the stack for the canvas @p e
4153 * resulting in the dev pointer in all events that get fed to the canvas
4154 * being the device at the top of the device stack for that canvas.
4155 *
4156 * If a device is pushed onto the device stack, it will not be deleted
4157 * until a canvas free OR until it has been popped from the stack even if
4158 * evas_device_del() is called.
4159 *
4160 * The device @p dev must have been created as a device for the canvas it
4161 * is pushed onto (and not another canvas).
4162 *
4163 * Example:
4164 * @code
4165 * evas_device_push(canvas, dev);
4166 * evas_event_feed_mouse_move(canvas, 20, 30, 0, NULL);
4167 * evas_device_pop(canvas);
4168 * @endcode
4169 *
4170 * @see evas_device_pop
4118 * @since 1.8 4171 * @since 1.8
4119 */ 4172 */
4120EAPI void evas_device_push(Evas *e, Evas_Device *dev); 4173EAPI void evas_device_push(Evas *e, Evas_Device *dev);
4121 4174
4122/** 4175/**
4176 * This pops the top of the device stack for the canvas
4177 *
4178 * @param e The canvas to pop the device stack from
4179 *
4180 * This pops the top of the device stack making the current device context
4181 * used for device events being what is now at the top of the stack after
4182 * popping.
4183 *
4184 * @see evas_device_push
4123 * @since 1.8 4185 * @since 1.8
4124 */ 4186 */
4125EAPI void evas_device_pop(Evas *e); 4187EAPI void evas_device_pop(Evas *e);
4126 4188
4127/** 4189/**
4190 * List all current devices attached to the given canvas and/or device
4191 *
4192 * @param e The canvas to query for a device list
4193 * @param dev A specific device inside the canvas to query for child devices or NULL if just querying the base canvas devices
4194 * @return An internal list of Evas_Device pointers, or NULL if no devices are found
4195 *
4196 * This will list all devices belonging to a specific evas canvas @p e, at the
4197 * top-level in the device tree if @p dev passed in is NULL. If @p dev is
4198 * a valid device for the given canvas @p e, then a list of child devices
4199 * of @p dev will be returned, allowing you to walk the device tree.
4200 *
4201 * The list returned is only valid so long as no changes are made to the
4202 * device tree in the given canvas @p e. If there are no devices or children
4203 * then NULL is returned.
4204 *
4205 * @see evas_device_parent_get
4206 * @see evas_device_name_get
4207 * @see evas_device_description_get
4208 * @see evas_device_class_get
4209 * @see evas_device_subclass_get
4210 * @see evas_device_emulation_source_get
4128 * @since 1.8 4211 * @since 1.8
4129 */ 4212 */
4130EAPI const Eina_List *evas_device_list(Evas *e, const Evas_Device *dev); 4213EAPI const Eina_List *evas_device_list(Evas *e, const Evas_Device *dev);
4131 4214
4132/** 4215/**
4216 * Set the name of a device as a string
4217 *
4218 * @p dev The device to set the name of
4219 * @p name The name string as a readable C UTF8 string
4220 *
4133 * @since 1.8 4221 * @since 1.8
4134 */ 4222 */
4135EAPI void evas_device_name_set(Evas_Device *dev, const char *name); 4223EAPI void evas_device_name_set(Evas_Device *dev, const char *name);
4136 4224
4137/** 4225/**
4226 * Get the name of a device
4227 *
4228 * @p dev The device to query
4229 * @return The device name string or NULL if none is set
4230 *
4231 * This gets the name set by evas_device_name_set(). This is a readable UTF8
4232 * C string, or NULL if no name is set.
4233 *
4234 * The name should be a short name like "Wireless Mouse", "Joystick",
4235 * "Finger", "Keyboard" or "Numberpad" etc.
4236 *
4138 * @since 1.8 4237 * @since 1.8
4139 */ 4238 */
4140EAPI const char *evas_device_name_get(const Evas_Device *dev); 4239EAPI const char *evas_device_name_get(const Evas_Device *dev);
4141 4240
4142/** 4241/**
4242 * Set the description of a device as a string
4243 *
4244 * @p dev The device to set the description of
4245 * @p name The description string as a readable C UTF8 string
4246 *
4143 * @since 1.8 4247 * @since 1.8
4144 */ 4248 */
4145EAPI void evas_device_description_set(Evas_Device *dev, const char *desc); 4249EAPI void evas_device_description_set(Evas_Device *dev, const char *desc);
4146 4250
4147/** 4251/**
4252 * Get the description of a device
4253 *
4254 * @p dev The device to query
4255 * @return The device description string or NULL if none is set
4256 *
4257 * This gets the description set by evas_device_description_set(). This is
4258 * a readable UTF8 C string, or NULL if no description is set.
4259 *
4260 * A description is meant to be a longer string describing the device so a
4261 * human may make sense of it. For example "Wireless 6 button mouse in Black
4262 * with red buttons" would be a good description, so a user may identify
4263 * precisely which device is being talked about.
4264 *
4148 * @since 1.8 4265 * @since 1.8
4149 */ 4266 */
4150EAPI const char *evas_device_description_get(const Evas_Device *dev); 4267EAPI const char *evas_device_description_get(const Evas_Device *dev);
4151 4268
4152/** 4269/**
4270 * Set the parent of a device
4271 *
4272 * @p dev The device to set the parent of
4273 * @p parent The new parent device
4274 *
4275 * This sets the parent of a device @p dev to the parent given by @p parent.
4276 * If the device already has a parent, it is removed from that parent's list.
4277 * If @p parent is NULL then the device is unparented and placed back as a
4278 * root device in the canvas.
4279 *
4280 * When a device is deleted with evas_device_del(), all children are also
4281 * deleted along with it.
4282 *
4283 * @see evas_device_del
4284 * @see evas_device_parent_get
4285 * @see evas_device_list
4286 *
4153 * @since 1.8 4287 * @since 1.8
4154 */ 4288 */
4155EAPI void evas_device_parent_set(Evas_Device *dev, Evas_Device *parent); 4289EAPI void evas_device_parent_set(Evas_Device *dev, Evas_Device *parent);
4156 4290
4157/** 4291/**
4292 * Get the parent of a device
4293 *
4294 * @param dev The device to query
4295 * @return The parent device or NULL if it is a toplevel
4296 *
4297 * This returns the parent device of any given device entry, or NULL if no
4298 * parent device exists (is a toplevel device).
4299 *
4158 * @since 1.8 4300 * @since 1.8
4159 */ 4301 */
4160EAPI const Evas_Device *evas_device_parent_get(const Evas_Device *dev); 4302EAPI const Evas_Device *evas_device_parent_get(const Evas_Device *dev);
4161 4303
4162/** 4304/**
4305 * Set the major class of device
4306 *
4307 * @param dev The device whose class to set
4308 * @param clas The class to set it to
4309 *
4310 * This sets the "primary" class of device (a broad thing like mouse, keyboard,
4311 * touch, pen etc.).
4312 *
4163 * @since 1.8 4313 * @since 1.8
4164 */ 4314 */
4165EAPI void evas_device_class_set(Evas_Device *dev, Evas_Device_Class clas); 4315EAPI void evas_device_class_set(Evas_Device *dev, Evas_Device_Class clas);
4166 4316
4167/** 4317/**
4318 * Get the major class of a device
4319 *
4320 * @param dev The devise to query
4321 * @return The device class to set
4322 *
4323 * This sets the device class set by evas_device_class_set().
4324 *
4168 * @since 1.8 4325 * @since 1.8
4169 */ 4326 */
4170EAPI Evas_Device_Class evas_device_class_get(const Evas_Device *dev); 4327EAPI Evas_Device_Class evas_device_class_get(const Evas_Device *dev);
4171 4328
4172/** 4329/**
4330 * Set the sub-class of a device
4331 *
4332 * @param dev The device to modify
4333 * @param clas The sub-class to set
4334 *
4335 * This sets the sub-class of a device whihc gives much more detailed usage
4336 * within a broader category.
4337 *
4338 * @since 1.8
4339 */
4340EAPI void evas_device_subclass_set(Evas_Device *dev, Evas_Device_Subclass clas);
4341
4342/**
4343 * Get the device sub-class
4344 *
4345 * @param dev The device to query
4346 * @return The device sub-class set by evas_device_subclass_set().
4347 *
4348 * @since 1.8
4349 */
4350EAPI Evas_Device_Subclass evas_device_subclass_get(const Evas_Device *dev);
4351
4352/**
4353 * Set the emulation source device
4354 *
4355 * @param dev The device being emulated
4356 * @param src The primary source device producing events in the emulated device
4357 *
4358 * Devices may not be real, but may be emulated by listening to input on other
4359 * devices and modifying or interpeting it to generate output on an emulated
4360 * device (example a fingeron a touchscreen will often emulate a mouse when
4361 * it presses). This allows you to set which device primarily emulates @p dev
4362 * so the user can choose to ignore events from emulated devices if they also
4363 * pay attention to source device events for example.
4364 *
4173 * @since 1.8 4365 * @since 1.8
4174 */ 4366 */
4175EAPI void evas_device_emulation_source_set(Evas_Device *dev, Evas_Device *src); 4367EAPI void evas_device_emulation_source_set(Evas_Device *dev, Evas_Device *src);
4176 4368
4177/** 4369/**
4370 * Get the emulation source device
4371 *
4372 * @param dev The device to query
4373 * @return The source emulation device set by evas_device_emulation_source_set().
4374 *
4178 * @since 1.8 4375 * @since 1.8
4179 */ 4376 */
4180EAPI const Evas_Device *evas_device_emulation_source_get(const Evas_Device *dev); 4377EAPI const Evas_Device *evas_device_emulation_source_get(const Evas_Device *dev);