Using createCharStyle

This article is part of the Scripts series.

Someone asked about the syntax for createCharStyle() on the mail list. The information in the online manual is clearly less than enough to understand how to use this command. My first attempts at making use of it couldn't even get past the traceback message, and the problem with traceback is that it tends to be at best cryptic, and at worst totally unhelpful.

Here is a slight translation I have done of the command as listed in its synopsis:

scribus.createCharStyle("name","font",fontsize,"features","fillcolor",fillshade,"strokecolor",strokeshade,baselineoffset, shadowxoffset,shadowyoffset,outlinewidth,underlineoffset,underlinewidth,strikethruoffset,strikethruwidth,scaleh,scalev, tracking,"language")

What I want to do is take these elements one by one and explain something about each. Notice that each one of these is either in quotes or not. If an element is in quotes, a string is expected and should be in quotes. If there are no quotes, then a numerical value is expected, and mostly a float value is appropriate. You do not, for example, put name="NameOfStyle", you just have "NameOfStyle" in its place between the quotes. As far as I know, single or double quotes can be used here.

You may also want to check Using createParagraphStyle.

My Method

What I did was to use a pre-existing script I had that created text frames and entered text. I then just inserted this element at some point wherever it was sure to be executed:

scribus.createCharStyle(yadayadayada)

The yadayadayada refers to gradually building up from left to right the commands and with success, adding more. One of the first things I could learn was that, even though the only required element was the name of the style, you can't just skip over elements. You have to consider how Scripter knows that a particular element corresponds to a particular feature, so this makes some sense.

So you then can recursively run this script, and then either look at your named style or try to apply it.

Command Elements

Only the first of these is said to be required, all others optional, however, you cannot skip over elements. For some strings, an appropriate entry might be a null string (""), but entering the number zero as a default may not work, for example, see fillshade below. Any numerical value can be a decimal.

name – a string with the name of the style. Again, simply enter this as "mystyle", not name="mystyle".

font – a string with the font name. The font style (italic, bold, condensed, book...) is provided here as part of the font name (example : font="Arial Italic"). The possible font names along with their style are listed in File > Preferences > Fonts under Font Name. So an appropriate entry here might be "DejaVu Sans Book", not "DejaVu Sans". If you enter a null value, Edit > Styles will show the default font but without a type (i.e., Regular or Book as applicable), so nothing will display if you apply it.

fontsize – a numerical value (float). Simply enter the number with no quotes.

features – a string containing one or more of the following: inherit,bold,italic,underline,underlinewords,strike,superscript,subscript,outline,shadowed,allcaps,smallcaps. Inside the quotes, separate items by commas but no spaces. The bold and italic choices seem to have no effect.

fillcolor – a string with a color from your color list. A curious thing happened when I entered a null value here. Edit > Styles said the color was None, but the font did have a brownish color (that stands for "undefined color"). Changing to color to None eliminated the color. Using "None" in your script does indeed make the color None.

fillshade – a numerical value. When you edit styles, you select a percentage, but here you use a decimal, so 1.0 = 100%, which you should enter for a default value.

strokecolor – a string with a color from your color list. The stroke color would be used for outline and also shadow if either are specified. If you enter a null value here, you can expect to see the mystery brown color.

strokeshade – a numerical value for stroke shade, see fillshade.

baselineoffset – a numerical value. When you edit this within Scribus, you see this as a percentage. Not only is this a decimal, but an odd one. If you enter 3, you get an offset of 0.3%. To actually get 3%, you would enter 30. All of the offset values can be 0 if you're not using them.

shadowxoffset – a numerical value. Just as with baselineoffset, this is a numerical value, where 30 equals 3% displacement in the X direction. Negative values are valid. You would need to specify shadowed in features or do this manually later to see this offset.

shadowyoffset – a numerical value. See shadowxoffset.

outlinewidth – a numerical value. Here again, this is a percentage in Scribus, entered here as a decimal, so that 30 equals 3%. This percentage is of the font size, so a 12pt font would have an outline of 0.36pt. If you're not using any of the -width settings, they could be 0 for a default.

underlineoffset – a numerical value. See the above offset entries.

underlinewidth – a numerical value. Analogous to outlinewidth.

strikethruoffset – a numerical value, as with the other offset values.

strikethruwidth &nadash; a numerical value. I hope you're seeing the pattern, as in outlinewidth.

scaleh – a numerical value for the horizontal scaling. While this is also a decimal for the percentage, note that here, 1.5 equals 150%. A default here would be 1.

scalev – a numerical value for the vertical scaling. Again, 1.5 equals 150%. A default here would be 1.

tracking – a numerical value, and a decimal for a percentage. Here 5 equals 0.5%.

language – a string for the language whose hyphenation rules will be applied. This is a language code, so appropriate entries could be "af", "ar", "bg", "bn", "br", "ca", "cs", "cy", "da", "de", "dz", "el", "en", "eo", "es", "et", "eu", "fi", "fr", "gl", "hu", "id", "it", "ja", "ko", "lt", "nb", "nl", "pl", "pt", "ru", "sa", "sk", "sl", "sq", "sr", "sv", "th", "tr", "uk", "zh". It's not clear that subdivisions, such as "pt_BR" make any difference here.