122
CHAPTER 5
G
ENERATING
USER
INTERFACES
• You have no method of telling the Dialog Wizard how to read and write data to
your API. For example, if your code is factored into a Model-View-Controller
model, you can’t adjust the Dialog Wizard to fit that model.
Because the Dialog Wizard is usually very valuable, the generator should provide com-
pelling value in these areas.
To separate the business details from the implementation details, first decide which
business details are important to capture:
• The data source to get and set the data
• The fields and their mapping to the dialog resource
• Validations for each field
• Cross-validations between fields
• Custom requirements on a per-dialog or per-field basis
With this information, the generator should be able to handle these details:
• Building the MFC infrastructure to create the control objects and mapping them
to the windows controls
• Building the data get and set code that initializes the controls properly and han-
dles the OK button press
• Implementing the field and cross-field validations
• Implementing or importing the code for custom requirements
Clearly the case for building this generator is not as compelling as the Swing generator
because of the excellent up-front work that Microsoft has done with the Resource
Editor and the Dialog Wizard. However, there are some scenarios where you should
make the investment in this generator:
• You are already generating a web interface for an application and you want a
client/server interface. This generator could use your existing web interface defi-
nitions to create the client/server dialog boxes.
• You are building an application with a large number of dialog boxes.
• The Dialog Wizard is not helping you because of your application data model or
other specific requirements.
• You are not satisfied with the data exchange and data validation (DDX/DDV)
model provided by the MFC and you cannot easily overcome those limitations
within the MFC framework or by using C++ inheritance or templates. 
5.6.2
Recommended tier generator architecture 
The tier generator model shown in figure 5.11 creates MFC dialog classes directly from
a set of business detail files written in XML.
Change font size pdf text box - Compress reduce PDF size in C#.net, ASP.NET, MVC, Ajax, WinForms, WPF
C# Code & .NET API to Compress & Decompress PDF Document
batch reduce pdf file size; pdf change font size
Change font size pdf text box - VB.NET PDF File Compress Library: Compress reduce PDF size in vb.net, ASP.NET, MVC, Ajax, WinForms, WPF
VB.NET PDF Document Compression and Decompression Control SDK
change paper size pdf; pdf markup text size
T
ECHNIQUE
GENERATING
MFC 
DIALOG
BOXES
123
Using the business detail and custom code input files, the generator takes a set of tem-
plates and creates the MFC dialog classes. The generator also validates the resource
mappings in the business detail files against the resource (.rc) file.
5.6.3
Processing flow 
The processing engine of the generator follows these steps:
Reads and validates the definition XML files and stores the information in
local structures.
Checks for any custom code references. Reads in the code files and stores them in
the local structures.
Reads in the resource file and stores the dialog boxes and their control IDs and
types.
Checks the local structures against the dialog boxes and controls that were read
from the resource file.
Merges the control type information in the .rc file with the definition file so you
know which code templates to use to handle the control.
Iterates the following steps over every dialog box defined in the XML file:
Initializes code caches that will be used for the CPP and HPP files.
Iterates over each field and follows these steps:
Builds and caches the field definitions for the HPP file and the constructor 
code for the CPP file.
Builds the event handlers for the CPP file and adds the prototypes to the 
HPP method list.
Generator
DefinitionFiles
C++MFCDialogs
Dialog
Class
Table
Checkbox
Dropdown
CustomCodeFiles
Validations
Event
Handlers
Resource(.rc)file
ApplicationLogic
Figure 5.11 1 A generator that builds the C++ for MFC dialog boxes 
MFC generator
C# PDF Text Box Edit Library: add, delete, update PDF text box in
Support to change font color in PDF text box. Ability to change text size in PDF text box. Adding text box is another way to add text to PDF page.
adjust size of pdf file; pdf files optimized
C# PDF Annotate Library: Draw, edit PDF annotation, markups in C#.
Support to add text, text box, text field and crop marks to PDF document. Able to edit and change PDF annotation properties such as font size or color.
pdf page size; can pdf files be compressed
124
CHAPTER 5
G
ENERATING
USER
INTERFACES
Adds any custom per-field code to the CPP file and adds the prototypes to 
the HPP method list.
Handles any per-dialog custom code by adding the code onto the HPP and CPP
code caches.
Uses the Dialog Class CPP template to create the implementation for the class.
This template should contain the class, the constructor, destructor, and message
map. The code text from the field processing steps should be merged in. Stores
the output of this template in the CPP file with the correct name.
Uses the Dialog Class HPP template to create the header for the class. This 
template should have the infrastructure methods (e.g., constructor and 
destructor). The template should then merge in the code created during the 
field processing. Stores the output of this template in the HPP file with the 
correct name.
5.6.4
Recommended mixed-code generation architecture 
An alternative to tier generation for MFC classes is to use a mixed-code generation
model on top of the mixed-code generation model already used by the Class Wizard. If
your requirements are simple enough to fit into this model, then you will still be able
to use the Class Wizard, which is not an option in the tier generator described previ-
ously. Figure 5.12 shows the mixed-code generation model.
In this generator, you look for your own custom comments and augment them
with custom code. As with the mixed-code generator shown in chapter 4, the gener-
ator takes its input from the comments to generate the code for implementing the
comment, and then replaces the existing comment with the original comment plus the
new code.
Generator
C++MFCDialogs
Dialog
Class
Table
Checkbox
Dropdown
Validations
Event
Handlers
Resource(.rc)file
ApplicationLogic
Figure 5.12 2 A generator that builds MFC dialog boxes using the C++ dialog 
boxes in a manner similar to the Class Wizard
C# PDF insert text Library: insert text into PDF content in C#.net
Powerful .NET PDF edit control allows modify existing scanned PDF text. Ability to change text font, color, size and location and output a new PDF document.
change font size in fillable pdf form; change pdf page size
C# PDF Sticky Note Library: add, delete, update PDF note in C#.net
Allow users to add comments online in ASPX webpage. Able to change font size in PDF comment box. Able to save and print sticky notes in PDF file.
change font size pdf; reader pdf reduce file size
D
ESIGN
TIPS
125
If your implementation only requires modification to the CPP or HPP file, you
should consider integrating the generator into the Microsoft Studio Visual C++
MSVC IDE so that you can access it from the menu and have the generator work with
standard I/O.
5.6.5
Processing flow 
Here is a very basic process flow for this mixed-code generation model. You will have to
adapt it to suit your requirements:
Reads in both the CPP and HPP files
Scans the files for your special comments
Performs these steps for each comment:
Parses any information required for generation from the comment
Generates the code based on the information in the comment using a template
Replaces the comment with the original comment text and the generated code
Creates backups of the CPP and HPP files
Replaces the CPP and HPP files with the next text
5.7
D
ESIGN
TIPS
Here are some tips on how to design your solution up front so that you can generate
large portions of the UI at implementation time.
• Try to break down your interface into three or four large types of interaction
models. Database application HTML pages, for example, usually break up into
table, form and query pages. 
• Recognize that in most systems there will be more than a few exception cases that
cannot be generated. The login page of a web application is a good example. In
some cases, this means providing for custom code; in others, it means that the
page will need to be handwritten. 
• For HTML pages, design your pages as a set of nested components and contain-
ers so that you can build consistency and quality through reuse. 
• Again on HTML pages, work with designers and product management staff to
keep the page flows simple and consistent. This will make the pages easy to gen-
erate and to use.
• For dialog boxes, try to establish two or three basic layouts for tabs and controls.
• Also when building dialog boxes, you may want to use the nested template archi-
tecture that was implemented in the case study in section 5.4 to create the popu-
lar sand struts style of layout.
MFC generator mixed-code generator architecture
C# PDF Field Edit Library: insert, delete, update pdf form field
Support to change font size in PDF form. RasterEdge.Imaging.Font.dll. pdf"; String outputFilePath = Program.RootPath + "\\" Output.pdf"; List<BaseFormField
change font size in pdf fillable form; change font size pdf fillable form
VB.NET PDF insert text library: insert text into PDF content in vb
Save text font, color, size and location changes to Other robust text processing features, like delete and remove PDF text, add PDF text box and field.
change font size pdf form reader; adjust size of pdf in preview
126
CHAPTER 5
G
ENERATING
USER
INTERFACES
5.8
T
OOLS
FOR
GENERATING
UI
S
Here is a list of web sites where you can find tools available for purchase off the shelf to
generate user interfaces:
• CodeCharge (www.codecharge.com/studio/) has an integrated development
environment that can generate a single interface definition to multiple target
environments (JSP, ASP, etc.).
• Visual Studio (http://msdn.microsoft.com/vstudio/) has interface tools and a
Class Wizard that will write some of the Win32 dialog management code for you.
• X-Designer (www.ist.co.uk/xd/index.html) can generate code for a number of
different platforms from a single definition.
• Proc-Blaster from Lockwood Software (www.lockwoodtech.com/index_pb.htm)
uses template-based code generation, as we discussed in section 5.4.
5.9
S
UMMARY
Don’t fall prey to the idea that code generation will make your pages bland. Code gen-
eration can build user interfaces that are of high quality, consistent, and elegant. Hand-
tweaking tags and JSP code on hundreds of pages is wasted engineering time.
The user interface is easily one of the highest impact areas to use code generation.
Find a small portion of your project and use it to try one of the solutions in this chap-
ter. You’ll see immediate productivity and quality improvements, and you’ll quickly
be sold on this powerful technique. 
In the next chapter, we’ll look at ways of using code generation techniques to create
documentation for several types of applications. 
C# PDF Convert to Word SDK: Convert PDF to Word library in C#.net
PDF document, keeps the elements (like images, tables and chats) of original PDF file and maintains the original text style (including font, size, color, links
pdf compressor; pdf reduce file size
VB.NET PDF delete text library: delete, remove text from PDF file
Functionality to remove text format by modifying text font, size, color, etc. Other PDF edit functionalities, like add PDF text, add PDF text box and field.
change paper size in pdf document; pdf change font size in textbox
127
C
H
A
P
T E R
6
Generating documentation
6.1 The importance of structured 
comments 128
6.2 The big picture e 129
6.3 A case study: augmented 
SQL code e 129
6.4 Understanding the JavaDoc and the 
Doclet API I 137
6.5 Finding a tool to do it for you u 137
6.6 Summary y 138
It seems that every new language promises “self-documenting code”—code so clear
that an engineer will be able to divine its purpose just by reading it. No commonly
used language has ever succeeded at meeting the self-documenting challenge, but a
few advances have made it easier for us to create well-documented code. Tools such as
POD (for Perl), JavaDoc (for Java), and Doxygen (for C++) allow you to put specialized
comments in your file along with your code. You can then employ a special tool
to parse the code, extracting the comments and the code structure, and automatically
generate documentation.
Even though you are using comments, the design is not to provide low-level, line-
by-line documentation. These tools support capturing the design intent close to the
code that implements that design. In this way, you keep your knowledge about the
design maintained with the code. The code, the technical documentation, and the API
aspect of the design documentation are all maintained as one unit and checked in and
out of source code control as one unit.
You can use code generators to interpret inline documentation and turn it into
external documentation in HTML, PDF, and other forms. If you understand how
documentation generators work, you can build your own generators and extend the
usefulness of your existing inline documentation.
128
CHAPTER 6
G
ENERATING
DOCUMENTATION
This chapter introduces a new generator that supports structured comments in
SQL files. After adding structured comments to the SQL code, you can run the
generator on the code and the generator will output a set of HTML files that docu-
ment the schema. We’ll use a JavaDoc format for the structured SQL comments.
6.1
T
HE
IMPORTANCE
OF
STRUCTURED
COMMENTS
The fragment of Java code shown in listing 6.1 is augmented with JavaDoc comments.
(We explain JavaDocs in more detail in section 6.4.) The JavaDoc comments explain
the purpose of the class and describe all the member variables and methods. The Java-
Doc tool takes these structured comments and creates HTML documentation for the class. 
/**                                                            
* This class stores a name and value pair.                     
*/                                                            
public class NameValuePair {                                   
/** 
* The name                                                
*/                                                        
public String _name;                                       
/** 
* The value
*/  
public Object _value;
/**                                                        
* This constructor takes a name and value pair to build   
* the object.                                             
* @param name The name.                                   
* @param value The value.                                 
*/  
public NameValuePair( String name, Object value )
{   
// Setting the values                                    
_name = name; 
_value = value;
}   
}
q
Notice the proximity of the JavaDoc comment to the code element that it documents.
This proximity is the largest single value of this type of inline documentation. Docu-
mentation that is close at hand has a high probability of being maintained. If the docu-
mentation is in another file, or another system, it will likely fall out of sync with the
original code. By using JavaDoc, you check out the code and documentation, as well as
check it in, all in one logical unit.
Listing 6.1 1 Example of Java using  JavaDoc structured documentation standard
Constructor
documentation
e
Name and value pair 
class documentation
q
Instance variable 
documentation
w
Interior non-JavaDoc 
documentation
r
CASE
STUDY
AUGMENTED
SQL 
CODE
129
w
The second major advantage of inline documentation is simplicity. To write a JavaDoc
comment properly, all you need to do is add an asterisk to the beginning of the line,
then type the comment as you normally would.
e
If your method has arguments, you use the @param syntax to document each param-
eter. In the case of the constructor, you must document the incoming parameters. You
do this by using the @param syntax, which takes the first word as the argument name
and the rest of the string as the comment for the parameter.
r
JavaDoc is held separately from regular comments by using the /** … */ syntax. In
this way, it does not conflict with any standard comments spread throughout the file.
In this code, the comment identifying what goes in the constructor is ignored because
the // comment syntax is not used for JavaDocs.
Your documentation will stand a better chance of being both complete and up-to-
date if it is easy to maintain. And your well-documented code will in turn produce a
well-maintained application. Inline documentation tools, such as JavaDoc, put the
documentation right next to the code it documents. This simple format is easy to read
and means the documentation is more likely to be maintained throughout the life of
the software. 
6.2
T
HE
BIG
PICTURE
The case study generators in chapter 1, “Introducing code generation,” used a JavaDoc
to build documentation for all of the generated output code and libraries. This docu-
mentation is valuable not only for engineers who need to use the APIs internally to
build the application, but also for users of the external SOAP interface. If the SOAP
interface generator creates the Java client code, the JavaDoc embedded in that client
code can be used as documentation for the external interface. This means that, along
with the Java classes themselves, you can provide your customer with robust documen-
tation in HTML format that describes all of the classes, their member variables, and
their methods.
6.3
CASE
STUDY
AUGMENTED
SQL 
CODE
Perl, C, C++, and Java all have inline documentation standards. SQL does not have an
inline documentation standard despite its widespread use of complex tables and elabo-
rate stored procedures—which would benefit greatly from quality documentation.
For this reason, we’ve chosen to make the case study for this chapter a documentation
generator for SQL that uses a JavaDoc-style syntax.
130
CHAPTER 6
G
ENERATING
DOCUMENTATION
6.3.1
Roles of the generator
The SQL documentation generator in this case study has one big responsibility: It
builds the technical documentation for the SQL in your application, including all of
the tables and stored procedures. The generator does not take responsibility for:
• Designing the documentation.
• Creating the end-user documentation.
• Cataloging or documenting the SQL queries or operations in the application layer.
By drawing these clear lines of responsibility, you can confidently lay out the feature set
and the architecture for the generator.
6.3.2
Laying out the generator architecture
Let’s build the generator using the code munger model (see chapter 2, “Code genera-
tion basics,” section 2.1.1). We chose the code munger model because the input is
executable code and the output is an external form other than code. The generator will
take SQL as input and scan it for JavaDoc-style comments. Then, using templates, the
generator will build a page for each table and an index page that contains references to
all the pages. Figure 6.1 shows the I/O flow for the SQL documentation generator. 
Keep in mind that all of the tables must be included in a single generation run.
That way, you can ensure proper linkages between table pages in the documentation.
The next step is to design the JavaDoc-style syntax. SQL does not support the /**
… */ comment syntax, so we developed a syntax for the comments based on the ANSI
standard—the comment syntax. Here is some example SQL marked up with the Java-
Doc syntax:
-- Book contains information about each book, the title,               
-- the author, the publisher, etc.                                     
--
-- @field bookID The primary key id                                    
-- @field title The title of the book                                   
-- @field ISBN The ISBN number of the book
-- @field authorID The author (as a foreign key relation)
-- @field publisherID The publisher (as a foreign key relation)
-- @field status The active or inactive state of the record
-- @field numCompies The number of copies in the library
Generator
HTMLDocumentation
HTML
Templates
HTMLIndex
SQLCode
Figure 6.1
The input and output flow for the 
SQL documentation generator
Documentation 
for each field
w
General docu-
mentation for 
the table
q
CASE
STUDY
AUGMENTED
SQL 
CODE
131
-- @relates_to Author                                                  
-- @relates_to Publisher                                               
create table Book ( 
bookID integer not null primary key 
,title varchar(80) not null 
,ISBN varchar(80) not null unique 
,authorID integer not null 
,publisherID integer not null 
,status integer not null 
,numCopies integer not null 
);
q
Comments outside of the @key syntax are related to the body of the table itself. Here, the
text starting with Book contains… is taken as a description of the Book table itself.
w
The @field syntax is directly followed by the field name. The words that follow it are
considered documentation for the specified field. In this case, the bookID field is doc-
umented with the following text: The primary key id.
e
The @relates_to key is used to specify relations between tables. The Book table is
related to the Author and Publisher tables, so there are two @relates_to items, the
first for Author and the second for Publisher. The HTML output should include links
to the Author and Publisher documentation from the Book page because of these
@relates_to keys.
6.3.3
Processing flow 
As it goes about its job of creating HTML documentation for your SQL code, the gen-
erator follows a series of steps:
Reads the input SQL file.
Tokenizes the SQL input.
Parses the tokens to read the comments and the structure of the tables.
Initializes a list of all pages.
Follows these steps for each table:
Creates a page using the HTML template that contains the name of the table, 
a description of the purpose of the table, the fields of the table with their 
types and any description, and links to any pages for the tables to which this 
table relates.
Stores the name of this page in the list of all pages.
Creates the HTML with the list of all the table description pages.
Documentation for 
table relationships
e
SQL documentation generator
Documents you may be interested
Documents you may be interested