ALL POSTS

Donate
for future development of Onetastic
(Why?)

Sep 20
2012
Macro Tutorial

Macros are built using the Macro Editor which can be launched from New Macro or Edit Macros buttons on the ribbon. See this post for more details. Macro Editor looks like below:

Macro editor

Here you can set the name, category and description of the macro and below that you can see the set of commands at your disposal on the left and the macro you are building on the right. You can use the Add and Remove buttons to build your macro. Before diving into all the details here, let's take a look at a simple macro and see how macros are built and how they work. Then we can slowly move into more aspects of macros.

Finding and modifying objects

This macro increases font size of all text on the current page by 1pt. The macro looks like this:

Macro screenshot - Modify Properties

As simple as that. The macro finds text in the current page and modifies its "fontSize" property by adding 1 to it. The blue underlined parts are pieces you can click and change to edit the macro. For instance you can click on "Text" and pick a different object type:

Macro screenshot - Modify Properties

Similarly you can pick the property you want to modify and how you want to modify.

Using conditions to filter objects

When querying for objects on the page, you can make use of conditions which are in the form of:

Macro screenshot - Filter objects

For example if you want to find paragraphs that are edited by "John" and are inside a table which is partially selected, you can do so by:

Macro screenshot - Filter objects

You can combine the "Is under" and "That has" to build more complex conditions. You can add as many of them as you need to specify the objects you are interested in.

Using variables for temporary storage

You can make use of variables, for temporarily storing and manipulating information. For instance if you want to read the text in a table cell and fill the rest of the table with that text, you can temporarily store the text of the first cell in a variable:

Macro screenshot - Variables

This macro stores the "text" property of the first table cell in to a variable named "TextOfFirstCell" and then reuses that to set the text for all the table cells. To add more variables or use existing variables, simply click on the blue underlined part in the Modify line and choose one of the options:

Macro screenshot - Variables

As you can see, you can choose either a property or a variable (existing or new) to modify here.

Using conditions to selectively apply modifications

You may want to apply modifications based on different conditions. The "That has" and "Is under" filters somewhat give you that but once that filter applied and you have the set of objects you can't make further decisions using them. To provide this, you can use If/Else clauses. Let's say you want to highlight text based on author:

Macro screenshot - Conditions

You can build very complex conditional statements using these and selectively apply any modifications. "If" can also evaluate conditions on variables and can use one or more of the following conditional operators, based on the values compared:

Macro screenshot - Conditions

Using indices to store set of values in variables

Macros support storing a set of values in variables as pairs. Indices are the way to achieve this. To explain that let's use an example: Copy the values of the first row into the second row in a table.

Macro screenshot - Indices

Here we check the "rowIndex" property of each cell. The first row is where rowIndex is 0, and the second row is where rowIndex is 1. We store text from each cell in the first row in the variable named "Text", indexed by the column index (colIndex property). This way we can store the text from the first row as pairs and then reuse it in the next row to set the text for the second row. To add an index to a variable use the "Add index to variable X" option on the variable selector:

Macro screenshot - Indices

This will add the index and you can then choose what to use as an index.

Using constant literal values

You can use constant literal values in the right hand side of That/Modify/If clauses. In fact we already did in most of the above examples. When you click to change the right-hand-side, you will see the list of properties and variables and an option to "Enter literal value". Also if the left-hand-side is a property with known set of values, you will see them there:

Macro screenshot - Literals

Here selection property can be one of "none", "partial" or "all", so you get to choose from one of them. Alternatively you can enter the value manually.

Asking user for input

You can ask user for input during macro execution to modify behavior of the macro. To do so, add a Modify clause and choose a variable for the left-hand-side. For the right hand side choose "Prompt user for value". This will open a dialog to enter details of the user input. For instance if you are building a macro that will search for some text (e.g. Search and replace) you may ask the user for the search term:

Macro screenshot - User Prompts

Macro screenshot - User Prompts

Here you can:

  • Add a message for the user (or choose a variable that contains the message),
  • Choose input type which can be one of
    • text
    • dropdown
    • checkbox
    • Message
  • Set an initial value for the input (for text and dropdown)
  • Set possible values (for dropdown only)
  • Specify whether user is allowed to leave the input empty (for text only)

This will prompt the user for input while executing your macro. The above options will result in the following dialog:

Macro screenshot - User Prompts

See how the message and initial value is placed. If you have multiple consecutive user prompts, Onetastic will merge them into a single user dialog. For instance see the following dialog for the Search & Replace macro:

Macro screenshot - User Prompts

Macro screenshot - User Prompts

As you can see 4 Modify clauses are turned into a dialog box with 4 inputs. This also shows different input types: text for "Find what" and "Replace with", dropdown for "Scope", and checkbox for "Match case". You can also see the underlined shortcut keys (like F in Find what), which comes from the & characters right before the corresponding letter. This is standard Windows way of specifying accelerators for labels. Hitting Alt+F will move the cursor to the "Find what" box. Finally, for the first input it is specified that user cannot leave it empty, therefore the OK button is not enabled until user types into it.

Macro Logging

When you run your macro, if it doesn't seem to be doing what you expect it to be doing, there is a way to generate logs from the execution to investigate the cause. To do so, go to the Settings and check Enable Macro Logging in the ribbon and re-run your macro. This will generate a macrolog.txt file under %appdata%Onetastic. You can see what operations took place and what the values of variables and properties were in the log file.

Conclusion

Hopefully this gives you some idea about how to build macros with Onetastic. You can also look at existing macros in the Macro Editor by going to Edit Macros dropdown. You can inspect the macro and try to understand how it works.

Update: A new tutorial about inserting text using a macro is available here.

Comments

Name
Comment
mmo - 2013-05-24
Thanks! you may want to note that somewhere on the download pages. IMHO that's not exactly selfevident, at least not for someone new to Onetastic.
Omer Atay - 2013-05-23
mmo, you need to execute the downloaded file by double clicking on it. That will install the macro.
mmo - 2013-05-23
Where to save downloaded macros to?
I must be missing the obvious, but if I download a macro (from Macroland or from anywhere else), where the heck do I have to save it to? I tried and simply saved it in my usual Download-folder but of course that alone doesn't make it show up in Onetastic's list of available macros. So, I suppose there is a "well-known" directory somewhere where one has to save such macros to so that Onetastic can locate them at startup time and loads them. But the documentation doesn't describe where this "well-known" folder is...
M.

Other Posts