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:
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 objectsThis macro increases font size of all text on the current page by 1pt. The macro looks like this:
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:
Similarly you can pick the property you want to modify and how you want to modify.
Using conditions to filter objectsWhen querying for objects on the page, you can make use of conditions which are in the form of:
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:
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 storageYou 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:
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:
As you can see, you can choose either a property or a variable (existing or new) to modify here.
Using conditions to selectively apply modificationsYou 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:
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:
Using indices to store set of values in variablesMacros support storing a set of values in variables as <key, value> 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.
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 <colIndex, text> 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:
This will add the index and you can then choose what to use as an index.
Using constant literal valuesYou 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:
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 inputYou 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:
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
- 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:
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:
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 LoggingWhen 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.
ConclusionHopefully 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.
Update 2: You can now upload your macros to Macroland. See more info here.