SharePoint Development from a Documentation Perspective

Andrew May

February, 2004

  • Andrew May's WebLog

    Working with group wizard shapes

    • 1 Comments

    When I was discussing shape-level wizard properties the other day, I mentioned group wizard shapes, which are related to, but independent from, the publication and page-level wizards. So here’s where I explain what I meant.

    Like wizard publications and wizard pages, group wizard shapes are pre-designed, and can morph. In Publisher, morphing refers to an object’s ability (be it a shape, page, or entire publication) to change its appearance based on the user’s choice of design. Choose a different design, and Publisher automatically updates the object according to the design chosen. So group wizard shapes are exactly what their name implies: grouped shapes that can automatically change appearance based on the design chosen for them.

    Here’s where they differ from publication or page wizards:

    ·          You can add group wizard shapes to any publication, whether or not it’s based on a publication wizard.

    ·          You set the design of each group wizard shape individually. This means that the appearance of each group wizard shape is independent from any wizard the publication is based on, as well as any other group wizard shapes you might have added to the publication. This applies only to the group wizard shapes you insert into the publication.

    Group wizard shapes have a Shape.Type property of pbGroupWizard. You add them to a page’s Shapes collection by using the AddGroupWizard method, which lets you specify the group wizard type (calendar, navigation bar, coupon, etc.) as well as the design to apply to the shape. Other than morphing, group wizard shapes can generally be manipulated like any other grouped shape.

    In the UI, group wizard shapes are called Design Gallery Objects, and are available from the Insert menu.

    How group wizard shapes interact with publication or page-level wizards

    My second bullet point above does have a caveat, as I mentioned, it only applies to the group wizard shapes you insert into the publication. Some publication or page wizards include group wizard shapes as part of certain designs. For instance, some newsletter wizard designs include table of contents shapes, and some web site wizard designs include navigation bars.

    In these cases, the group wizard shape does automatically update if you change the wizard design the publication is based on. But, here’s where things get confusing: it matters how the shape is added to the publication. If the group wizard shape is added as a publication or page-level wizard option, then Publisher treats it as belonging to the publication wizard; that is, Publisher updates the shape when the publication wizard is changed. However, if you add the group wizard shape using the Shapes.AddGroupWizard method, Publisher treats it as independent of the publication wizard.

    As with any other shape, you can determine whether a group wizard shape is part of a publication or page-level wizard design by getting its WizardTag property; if it’s anything but zero, it’s part of the wizard design.

    To illustrate this, consider the following two code samples. They both create a new publication based on a newsletter wizard, and then add a calendar, which is a group wizard shape, to the third page. The first example adds the calendar as a wizard page option. Because of this, Publisher treats the calendar as belonging to the publication wizard; change the wizard design, and the calendar’s appearance updates accordingly.

    Sub CreateNewsletterWithDependentGroupWizardShape()

        Dim newDoc As Document

        'create a newsletter publication

        Set newDoc = NewDocument(pbWizardNewsletters, 31)

        With newDoc.Pages

            'sets page 3 as active page

            newDoc.ActiveView.ActivePage = .Item(3)

            'adds a calendar to page 3

            If .Item(3).Wizard.Properties.FindPropertyById(44).Enabled = True Then

                .Item(3).Wizard.Properties.FindPropertyById(44).CurrentValueId = 2

            Else

                Debug.Print "This property is not enabled."

            End If

        End With

       

    End Sub

    In this case, the calendar is added using the AddGroupWizard method. Publisher treats the calendar as an independent group wizard shape; it does not update if the publication wizard design is changed.

    Sub CreateNewsletterWithIndependentGroupWizardShape()

        Dim newDoc As Document

        Set newDoc = NewDocument(pbWizardNewsletters, 31)

        newDoc.Pages(3).Shapes.AddGroupWizard _

            pbWizardGroupCalendars, Left:=72, Top:=72, Design:=16

       

    End Sub

    In this publication, the accent box shape in the upper left hand corner of the first page is a group wizard inserted by the publication wizard. The calendar you added is not. You can confirm this by running the following code (in the new document’s VBE window) with each shape selected in turn:

    Debug.Print ThisDocument.Selection.ShapeRange.WizardTag

    The accent box returns a wizard tag value of 2012; the calendar returns 0. the accent box updates when the publication wizard design is changed; the calendar does not. Note that if you change the color scheme, however, all the shapes that are set to color scheme colors update.

    For a general overview of publication and page-level wizards, see my article on MSDN:

    http://www.msdn.microsoft.com/office/understanding/publisher/articles/default.aspx?pull=/library/en-us/odc_pb2003_ta/html/odc_pb_createwizardpubs.asp

     

  • Andrew May's WebLog

    Identifying wizard shapes in a publication

    • 5 Comments

    I recently finished an article on how to generate publications based on pre-designed wizards in Publisher:

    http://msdn.microsoft.com/office/understanding/publisher/articles/default.aspx?pull=/library/en-us/odc_pb2003_ta/html/odc_pb_createwizardpubs.asp

    Here’s something I didn’t cover in the article, because it was a little more advanced than the basic overview-type article I was writing.

    But not only do publications and pages have wizard properties, but shapes do as well. Any shape that Publisher adds to the default appearance of a publication based on a wizard design has two properties that uniquely identify it. Publisher uses these properties to keep track of shapes that ‘belong’ to the wizard design, as opposed to any custom shapes the user might add to the publication later. If the user selects a different wizard design for the publication, Publisher ‘morphs’ the publication by changing the wizard shapes (adding, deleting, and changing shape properties) to the default appearance of the selected wizard design. Any shapes the user has added to the publication are left unchanged.

    WizardTag and WizardTagInstance are the two shape properties; together, they comprise a unique identifier for each wizard shape in the publication. WizardTag refers to the type and style of shape (a textbox of a certain style, a photo of a certain type, etc), while WizardTagInstance is the instance of that shape type in the publication. Every shape, whether generated by a wizard or not, has a WizardTag and WizardTagInstance property. For non-wizard shapes (that is, shapes that the user inserted into the publication), the value of each property is 0.

    There are several interesting aspects of wizard tags to keep in mind:

    ·          The instance numbering is not always consecutive, but it is predictable.  If you’ve got five instances of a certain shape type in your publication, don’t assume their WizardTagInstance values run from 1 to 5, because they probably don’t. From what I can tell, numbering appears to be consecutive within a given publication page, but not from page to page. For example, in the photo gallery wizard page, each page starts the first photo shape as a multiple of 64. Play with it before making any assumptions on how the instances are numbered.

    ·          While the WizardTag and WizardTagInstance property values are assigned by Publisher, and used to get track of the shapes generated by the wizard design, the properties themselves are not read-only. You can get and set them at will. Also, Publisher does not validate to guarantee a given WizardTag-WizardTagInstance combination is assigned to only one shape per publication. So you can easily set several shapes to have the same wizard tag and instance combination. In fact, if you wanted to treat these shapes as a subset of the wizard tag type, you might want to do this on purpose.

    ·          You can use the FindByWizardTag method (pass it a tag type and instance number) to return a specific instance, or even all instances of that tag. The method returns a ShapeRange collection. This is one of the few instances where you can create a Shapes collection that spans publication pages. For instance, if you wanted to apply formatting to all shapes of a certain wizard type (article textboxes in a newsletter, for instance), regardless of the page they appear on, this is how you’d do it.

    ·          Changing a shape’s WizardTag property to 0 excludes it from being updated the next time you change wizard designs. The most that will happen is that the shape’s colors may change. This is because the SchemeColor property for each ColorFormat object in the shape is still set; when Publisher changes the color scheme based on the wizard design, each color in the shape updates to the new color specified for that scheme color (Main, Accent1, etc.).

    Wizard properties for shapes should not be confused with group wizard shapes, which are a different beast altogether. I hope to write up a little something about group wizard shapes later in the week, as well as discuss the Tag property of Shapes. I should probably mention AutoShapes as well, just to make sure everyone’s totally confused.

    Until then…

  • Andrew May's WebLog

    Transferring Publisher custom color schemes between users and computers

    • 5 Comments

    I’ve spent some time the last few weeks helping my wife come up with a consistent corporate identity for her business: letterhead, business cards, and all that. (Of course, I’m the one that suggested the overhaul in the first place; that way, I get to play on the computer, and get points for being a supportive spouse. How can you beat that?)

    For a big part of this, of course, I’m working in Publisher. I wanted to take advantage of Publisher’s color schemes feature to create a set of custom colors for her business. And that’s when I discovered a few interesting things about transferring custom color schemes between users on the same computer, or different computers.

    The custom color schemes you create are not stored within the Publisher publication itself. Instead, they’re stored in a separate file, named custcols.scm, in your user directory. For example:

    C:\Documents and Settings\username\Application Data\Microsoft\Publisher\custcols.scm

    All the custom colors you as a user create are stored in this one file.

    Which leads to two limitations of color schemes, if you work on multiple computers, or have multiple users working with the same custom color scheme on the same machine:

    ·         If you open the publication on a different computer, the custom color scheme does not automatically get added to the color schemes available in Publisher on that computer.

    ·         If another user logs onto the same computer and opens Publisher, the color schemes you created are not available to them. Likewise, any color schemes they create won’t be available to you.

    Now, you can transfer custom color schemes by simply copying that custcols.scm file from one user directory to another, or even one computer to another. So once I’ve created the custom color scheme for my wife’s business, I can simply copy it into her user directory, and she’s ready to go. Likewise, she can copy it to her user directory on her machine at her business.

    A few important caveats apply, though:

    Publisher stores all the custom color schemes you’ve created in this one file. You can’t pick and choose which ones to transfer. Also, overwriting the custcols.scm file in this way will nuke any custom color schemes the user might already have in their existing custcols.scm file.

    Also, remember that the files aren’t linked in any way, so there’s no dynamic updating. If I change a custom color scheme while working in Publisher, I’d have to overwrite the custcols.scm file in my wife’s user directory again in order for her to use the updated scheme.

    A slightly more labor-intensive, but more precise, way to transfer custom color scheme is to use a Publisher file to transfer an individual color scheme. When you apply a custom color scheme to a publication, and then open that file using a different user and/or computer, the color scheme isn’t automatically added to the schemes available. However, the custom color scheme information still resides in the publication, and can be saved to the custcols.scm file.

    Here’s how you do it:

    1.      Define the custom color scheme and apply it to the publication.

    2.      Save the publication.

    3.      Open the publication on a different computer, or open it as a different user on the same computer.

    4.      In the Publisher task pane, click on Custom color scheme.

    5.      In the Color Scheme dialog box, on the Custom tab, the various colors of the custom color scheme are shown in the Current column. Without making any changes, click Save Scheme.

    6.      Enter the name of the custom color scheme, and click OK twice.

    Only the current scheme applied to the publication can be transferred in this way. However, since the custom color scheme is added to those currently saved in the user’s custcols.scm file, no previously-defined custom schemes are overwritten.

    Standard disclaimer: This posting is provided "AS IS" with no warranties, and confers no rights.

  • Andrew May's WebLog

    Choosing colors and inks for a publication

    • 2 Comments

    Looks like my next Publisher programmability article goes live on MSDN early next week. (Don’t worry, I’ll be sure and let you know what the link is once it gets published.) I’m really happy with this next series of articles, which highlight all the great functionality that went into 2003 to support commercial printing.

    This next article is the first of three aimed at showing commercial printers how to use the Publisher object model to automate getting Pub files ready for printing. This one covers color modes, print modes, and how to specify exactly what type of print output you want: separations, composite CYMK, etc.

    As I was looking it over, it struck me that the article could probably help anyone who needs to get Publisher files ready to hand off to a commercial printer. However, because the article is aimed at commercial printers, it assumes you already know about color modes, print modes, inks, plates, and all that. So in the selfish interest of widening the audience for my article, here’s a little background on some of the printing concepts touched on in the article.

    Specifically: color models, and how they relate to printing. Each color model is a way of thinking about color. In general, there are three color modes you need to be aware of: RGB, CMYK, and spot color.

    RGB (Red, Blue, Green)

    This is the color mode that is probably most familiar to people. It uses mixtures of these three primary colors to create the full range of colors. As we all know from a certain Pink Floyd album cover, white light splits into distinct types of colored light when refracted through a prism. Specifically, it separates into three primary colors: red, blue, and green. (Yes, we were taught it splits into the Roy G. Biv spectrum in school, but those other colors are actually just mixtures of the primaries.) For this reason, the RGB color mode is sometimes referred to as an additive color mode. The human eye actually contains three types of receptors, each structured to receive one primary color.

    Because it is based on the properties of light, the RGB color mode is used by TVs, computer screens, and other display devices. It’s also used by scanners, because they capture an image by scanning it with focused light. RGB is also the standard for most desktop printers-- I’ll explain that later.

    RGB colors are expressed by a set of three numbers, one for each color. So your favorite purple might be (102, 51, 204).

    CMYK (Cyan, Magenta, Yellow, and uh…Black)

    This is the color mode most often used by commercial printers. It is also referred to as process color. This color mode can be thought of as the flipside of RGB, as it is based on the properties of ink, rather than light. When you combine the primary colors of light, you get white light. When you combine the primary colors of ink, you get black (well actually, kind of dark muddy brown, but we’ll get to that later.) Each of the three primary colors here, cyan, magenta, and yellow, is actually what you get when you filter out one of the RGB primary colors from white light. Filter out red, and you get cyan; filter out green, and you get magenta; ditch blue, and you’re left with yellow. For this reason, CMYK is sometimes referred to as a subtractive color mode.

    A fourth color, black (K), is added because the three primary inks by themselves don’t produce a crisp, deep enough black for printing purposes. K is used to designate black so as to not be confused with blue (the B in RGB).

    The CMYK (or process) color mode is the one used by most commercial print operations. Even if you give your printer a RGB publication, chances are he’ll have to convert it to CMYK before he prints it. So if you know you’re going to have a publication commercially printed, it’s good practice to define it as a CMYK publication from the start.

    CMYK colors are expressed by a set of four colors, one for each color. So that same purple would be (85, 81, 0, 1).

    Spot color

    This is the last major color mode, and it’s also based on the properties of ink. For spot colors, however, each color is printed using a specially-mixed ink, rather than combining inks as in RGB or CMYK. This is kind of like picking a paint color; you’re picking a special ink color from a manufacturer. Pantone has made a business out of defining custom colors like this. So that purple you want might be 16-1248 God Awful Bright Purple.

    (Getting Your Geek On side note: When is a color definition system like an operating system? Wired.com has an interesting take on Pantone’s efforts to expand their color definition standard here: http://www.wired.com/wired/archive/10.10/pantone.html)

    If you only have one or two colors (and that includes black) in your publication, and you’re getting it commercially printed, you might want to consider using spot color. That way, you end up using (and paying for) less inks. For example, if you have two colors in your publication, if you printed it as a CMYK publication, you’d still have to use four inks. Those four inks would by printed on top of each other on the printing press to create the two colors you wanted. If you set your publication up for spot color, you’d only use two inks: one for each color.

    One last note: you can combine CMYK and spot colors in a single publication. In this situation, most of the colors in the publication are blends of the CMYK inks, but one or more special colors that have to be an exact color are spot inks. For example, if you need the colors in your business logo to be absolutely, positively the right shade, and not just the closest approximation that mixing CMYK inks can produce, then consider printing those colors as spot inks.

    Now, having read this far, you’re asking: how come RGB is the color mode of choice for desktop printers, when they use ink (or at least toner) rather than light to display color? Here’s the deal:

    Desktop printers don’t take CMYK or spot color input. Which isn’t surprising, since most computer applications don’t provide CMYK color information. For example, Publisher is the only Office application, and I believe the only Microsoft app, that has CMYK capability. But all applications need to generate RGB information to even display information on your computer screen anyway. So as long as the printer can accept files with RGB information, then it’ll work.

    If you open up your company printer, you’ll find four (or more) toner cartridges. So what gives? Turns out that the printer is actually taking the RGB information you sent in your document, and converting it into CMYK values at the printer. In addition, some photo-quality desktop printers have more than just CMYK toners; some add O (orange) and G (green), or LC (light cyan) and LK (light black, better known as gray) toner cartridges.

    Make sense? For information on how to work with color modes in a publication, see the article.

    Standard disclaimer: This posting is provided "AS IS" with no warranties, and confers no rights.

  • Andrew May's WebLog

    Visio SDK available for download

    • 4 Comments

    We've just put the finishing touches on the Visio 2003 SDK and pushed it out the door:

    http://www.microsoft.com/downloads/details.aspx?familyid=557120bd-b0bb-46e7-936a-b8539898d44d&displaylang=en

     

    I mention this for two reasons:

    1. The SDK is one-stop shopping for developer reference material about the best version of Visio yet.
    2. I wrote or revised several of the technical articles included in the kit.

    So consider this my shameless plug for the day.

  • Andrew May's WebLog

    Setting a shape’s tool tip and alt text

    • 0 Comments

    Here’s another tip that concerns Publisher Shape objects. When you mouse hover over a shape on a publication page, Publisher displays the shape name as a tool tip. You can set the shape name to anything you want, and this becomes the tool tip displayed by Publisher on mouse hover.

    The default name of a shape is usually a generic shape type description, followed by a number that denotes the order in which shapes were added to the publication. For example, ‘Picture 12’ is a picture, and was most likely the twelfth shape added to the publication. When you mouse hover over a shape, Publisher displays the default shape name, minus the numbering; it displays ‘Picture’, as opposed to ‘Picture 12’.

    To set the name of a shape, just set the Shape.Name property to the string of your choice. If you end the string with a number, Publisher displays that too. For example, if the default name of a shape is ‘Picture 12’, Publisher displays ‘Picture’. But if you overwrite the default name and explicitly set the name to ‘Picture 12’, then Publisher displays ‘Picture 12’. Remember that each individual shape in a grouped shape also has a name which displays as you mouse hover. As far as I can tell, the group shape name only displays when you hover over the rotation tool on the grouped shape. To access the shapes in a grouped shape, use the Shape.GroupItems property.

    Shape names must be unique, however; trying to name multiple shapes the same thing generates an error.

    The tool tip that Publisher displays on mouse hover shouldn’t be confused with alternative text. Alternative text applies to web pages; it’s the text shown while an image is downloading, or if the user has their browser set to not displays pictures. It is completely separate from a shape’s name. By default, a shape’s alternative text is empty; Publisher does not set the default alternative text equal to the same name.

    To demonstrate this, do the following: create a blank web page, and insert several shapes on the page. Hover over them to see Publisher’s default tool tips. Then run the following code, which generates custom names and alternative text for each shape:

    Sub AddAltTextToShapes()

    Dim shpLoop As Shape

    Dim intCount As Integer

    intCount = 1

     

    With ActiveDocument.Pages

        For Each shpLoop In .Item(1).Shapes

            shpLoop.Name = "MyShape " & intCount

            shpLoop.AlternativeText = "Alt Text For MyShape " & intCount

            intCount = intCount + 1

        Next

    End With

    End Sub

    In the Publisher file, you can now hover over the shapes and Publisher displays the custom shape names. Preview the web page in your browser (File > Web Page Preview). Now set your browser to not display pictures, and refresh the page. (In IE, this options is buried here: Tools > Internet Options > Advanced > Multimedia > Show Pictures.) You should see the custom alternative text for each shape.

    Here’s a routine that sets the alternative text of a shape equal to that shape’s name. Just be aware that you can nest grouped shapes, so if you had grouped shapes several levels deep, you’d have to add recursive logic to set the alternative text for those nested shapes as well.

    Sub SetShapeNameAsAddAlt()

    Dim shpLoop As Shape

    Dim shpLoop2 As Shape

     

    With ActiveDocument.Pages

        For Each shpLoop In .Item(1).Shapes

            shpLoop.AlternativeText = shpLoop.Name

            If shpLoop.Type = pbGroup Or _

                shpLoop.Type = pbGroupWizard Then

                For Each shpLoop2 In shpLoop.GroupItems

                    shpLoop2.AlternativeText = shpLoop2.Name

                Next

            End If

        Next

    End With

    End Sub

  • Andrew May's WebLog

    Print Preview: what you see and what you get

    • 0 Comments

    Ever print something and have it be slightly different than what you saw in Print Preview? Conversely, ever go into Print Preview and see something that’s just a tad off from what your file actually looks like? For the most part, the differences are probably minor, but why does it happen at all?

    This situation usually occurs when the application file contains information that is not under its direct control; for example, OLE (object linking and embedding) objects, or EPS (encapsulated PostScript) files. Here’s what happens in Publisher in these cases, and I’m pretty sure this is standard throughout Office applications:

    Basically, when you select Print Preview, Publisher creates a .wmf (Windows metafile) file based on the contents of the publication. This metafile is what you see in the Print Preview window.

    OLE objects

    The application (that is, Publisher) creates a metafile to display the OLE object on the screen. When you choose Print Preview, it in turn creates a metafile of the Publisher file, including the metafile of the OLE object. So at this point, what’s display in Print Preview is a rendering of a rendering of the actual OLE content.

    When you print the file, Publisher calls the OLE server to find out what to print in place of the OLE object, and sends that raw information to the printer for printing.

    EPS files

    The application (Publisher) uses its built-in EPS filter to create a metafile of the EPS image. Note that Publisher does not use the bitmap preview image that’s usually included in the EPS file. Instead, it relies on its EPS filter, which interprets the PostScript, for more accurate (but still not perfect) rendering.

    What gets printed depends on whether you’re using a PostScript-enabled printer or not. For non-PostScript printers, the Publisher passes the metafile it created of the EPS, and that’s what gets printed. For printers that can handle the PostScript language, Publisher passes the raw EPS to the printer, and that’s what ends up on the page.

    Keep in mind that the Print Preview also takes into account information about the printer you have selected. For example, if you’ve selected a black-and-white printer, then your preview image is black and white, regardless of whether your publication contains color. Also, the clipping area (margin around the paper edge on which the printer cannot print) varies from printer to printer. This is reflected in the Print Preview image as well. So in general it’s best to select the printer you want before you print preview your publication.

  • Andrew May's WebLog

    Automating commercial prepress in Publisher article is now live

    • 0 Comments

    The title pretty much says it all. The first in a series of three articles dealing with using the Publisher object model to automate prepress processes for commercial printers is now live on MSDN:

    http://msdn.microsoft.com/library/?url=/library/en-us/odc_pb2003_ta/html/ODC_pb_Prepress1_.asp

    As I've mentioned in earlier posts, this one covers defining color modes and controlling print output. The Publisher team put a lot of effort into beefing up commercial printer support for Pub 2003, and it really shows. Take a look at these articles to get a run-down on all the great expanded printing functionality from an automation standpoint.

    The next article in the series should see daylight sometime next week. It deals with page setup, and managing graphics and design issues.

  • Andrew May's WebLog

    Automating commercial prepress part duex now live

    • 0 Comments

    The second part of my series on automating commercial printing tasks using the Publisher 2003 object model is now live on MSDN. This time around, we discuss how to automate, customize, and extend prepress operations involved publication page setup, embedded and linked pictures, and design considerations.

    This articles includes examples that use the Scripting Runtime library to manipulate files outside of the Publisher file that contains the VBA code; in this case, to perform preflight tasks on Publisher files found in a specified directory. This might be a good solution for commercial printers who don’t want to have to copy code into every Publisher file they preflight, but don’t want to go through the effort of turning their prepress automation routines in add-ins.

    Check it out:

    http://msdn.microsoft.com/library/?url=/library/en-us/odc_pb2003_ta/html/odc_PB_prepress2.asp

Page 1 of 1 (9 items)