Custom Cursors

Cursors are used in conjunction with on-screen overlays to help give a more immersive presentation or video. There are several cursors that come with Awesemulator by default. These should be adequate for most of your needs, but sometimes more specialized cursors are needed.

When looking for custom cursors the first place to start is the Cursor Gallery to see if someone else has already created a cursor suitable for your needs. If you still can't find what you are looking for then it's time to create your own custom cursor! This might sound like some work, but it's actually no more than getting a couple of images and creating a simple XML file in Notepad.

The following should provide you with all the information you need to get started. The steps below will be creating the cat from the WTF Cursor Pack available in the Cursor Gallery.

Common Reasons for Creating Custom Cursors

  • Use of a cursor not included with Awesemulator
  • Draw more attention to specific features of your app
  • Additional skin tones
  • Theme matching, for instance:
    • Fishing Lure for a fishing app
    • Paintbrush for a photo editor
    • Robot hand for a game about robots
    • Witches finger for a Halloween app
    • Lasers and more Lasers for an awesome app from the future

Creating Your Images

Cursor images are created for use when the emulator is at 100% zoom and are auto-scaled by Awesemulator by default (Although they can be scaled independently). This means we need pretty large images, but we only need the 2. Cursors are not rotated to match the emulator orientation and will always match the image file in terms of rotation/position.

Basic Image Properties:
  • image - Transparency is alpha blended (PNG is the recommended format for the best quality blending)
  • Designed for 100% Zoom - All other sizes are auto-scaled
  • 96 DPI - Not a strict requirement but will make your life easier
You can use whatever image editor you want, but one that supports layers and advanced editing will be a huge help. We use GIMP since it's free and does everything we need.

For this example we have taken a random cat image from the internet:
CatCursor.png
To make the press image we did some amazing editing and bent the arm to make it look like the cat is swatting at something. The images shown above have been scaled down to fit on this page but are actually about twice the size shown. The images are also not a single image as shown but are 2 separate files. The Red dot has also been added for illustrative purposes to show where we placed the Hotspot ("Click Point"). So now we have 2 cat images. This is all that's required to make this whole thing work.

An easy way to determine the Hotspot is to use a program like GIMP that shows current coordinates of the mouse within the image. Hover over where you would like the hotspot to be and note the coordinates in the bottom left of the screen:
HotSpotFinder.jpg

Setting up the Configuration File

Awesemulator Configuration files are simply XML files (specialized text files) that can be created and edited in your favorite text editor (such as Notepad). They are stored in the Configuration Folder and are pretty simple to make. The easiest way is to cut and paste the example below and customize it. To be recognized by Awesemulator they need to be named *.Cursors.xml (our Cat example is part of a collection named WTF.Skins.xml).

Each XML file will be validated (any failures will be listed in a log within the Configuration > Validation folder) to ensure all necessary information is provided. For specific questions about the XML and acceptable values, please refer to the Cursor XML Reference - but it's really not that complicated.
WTF.Skins.xml
<?xml version="1.0" encoding="utf-8" ?>
<!--
    WireBear Awesemulator
    Created by Chris Kent
    Copyright 2011 WireBear. All rights reserved
    
    Example of how to make additional cursor definitions. See Default.Cursors.xml for information
    about what to put in each attribute. To create a cursor definition, you just need 2 images
    (standard and pressed) and a definition file like this located somewhere in the Configuration
    folder named *.Cursors.xml (ie WTF.Cursors.xml). The cursor definition needs a Cursors root element
    and then one or more Cursor elements.
    
    Got a robot game? Create a robot finger. Got an undersea adventure? Create an Octopus Tentacle.
    Halloween app? Maybe a witch finger or zombie hand. Totally up to you. Got a good one? Why not share
    it with everyone else. Find details on http://wirebear.com or http://awesemulator.codeplex.com.
-->
<Cursors>
  <Cursor Name="Cat" Purpose="???" HotspotX="279" HotspotY="18"
          ImageFile="Configuration/Images/Cursors/Cat.png"
          PressedImageFile="Configuration/Images/Cursors/CatPress.png"
          Author="WireBear"/>
  <Cursor Name="Cow" Purpose="???" HotspotX="25" HotspotY="164"
          ImageFile="Configuration/Images/Cursors/Cow.png"
          PressedImageFile="Configuration/Images/Cursors/CowPress.png"
          Author="WireBear"/>
</Cursors>

The above configuration file follows the basic structure of a Cursor Configuration file (Header, Comments, Cursors Element). Fill in the comments section with whatever you want - generally who you are, any copyrights/attributions, license information, special instructions, etc. Comments are not required, they are just a good idea.

The Cursors Element shown above contains two Cursor elements which is fine (it can contain as many cursor elements as you want), but in general a cursor configuration file will only have one. The Cursor attributes are pretty self explanatory but here's a quick rundown of important information: (Again, see Cursor XML Reference for details)
  • The name show in the dropdown(s) in Awesemulator are just a combination of the Name and Purpose values: Name (Purpose) so, in the Cat example above the dropdown will read: Cat (???)
  • Names do not need to be unique but you should do it anyway to make things easier for the end user
  • HotspotX and HotspotY correspond to the "Click Point" of the cursor
  • ImageFile and PressedImageFile are relative (to Awesemulator) paths to the main image and the pressed image to use.
    • Generally cursor images are stored in the Configuration > Images > Cursors directory, but this is not a strict requirement and you could create all the nested folders your heart desires
    • It's also pretty typical to name your Pressed Image the same as your main image with just the word press on the end (ie Cat.png and CatPress.png)
  • Author is never actually used, just provided for anyone looking through your config file

Testing Your Cursor

The easiest way to test your cursor is to place the image files and the XML Configuration file in the Configuration Folder and using the Advanced Menu have Awesemulator reload the settings every time you make a change to the config file.


Once you've got a working cursor, please share it with us! Check out the Distribution of Custom Assets Guide to find out how simple it is (Zip and email).

See Also

Last edited Sep 8, 2011 at 3:12 PM by theChrisKent, version 2

Comments

No comments yet.