.. index:: library class multiple source files using library class .. _library-classes: Library Classes ======================== .. index:: library; UIF In :ref:`Returned-Function-Values`, the suggestion was made to look at the Painter class and split out repeated ideas into functions, leading to a function to prompt the user and return a double value. The same section included the example program :repsrc:`addition2/addition2.cs`. In that case there were repeated prompts for integers. Clearly another common situation is to prompt for a string. We can create functions to do all these things and more, and embed them into a class specially written for a new interactive program. A neater thing is to put them as a class in a separate library that can be used directly for multiple programs. We can create functions ``PromptLine``, ``PromptInt``, and ``PromptDouble``, and put them in their own class, ``UIF`` (for User Input First version) in project ui's file :repsrc:`uif.cs `. We explain the namespace line after the code: .. literalinclude:: ../../examples/introcs/ui/uif.cs .. index:: namespace IntroCS namespace We have been ``using System`` in every program. ``System`` is a *namespace* that collects a particular group of class names, making them available to the program, and distinguishes them form any classes in a different namespace that might have the same class names. Once we start writing and using multiple classes at once, it is a good idea for us to specify our own namespace. We will consistently use ``IntroCS`` in our multi-file examples in this book. .. index:: public Specifying a namespace makes it possible for all other classes in the same namespace to reference *public* parts of the current class, and vice-versa. Public classes and functions start their heading with ``public``. The code included in a namespace is enclosed in braces, so the general syntax is | ``namespace`` *name* | ``{`` | class definition(s)... | ``}`` We will keep user input library classes like this one, :repsrc:`uif.cs `, in a project ui. Notice that the functions we want accessible in ``UIF`` are all marked ``public``, so that any class can use them. We can write a modified example addition program, :repsrc:`addition3/addition3.cs`, as an example of using ``UIF``: .. literalinclude:: ../../examples/introcs/addition3/addition3.cs To allow access to UIF, we have added the IntroCS namespace for the class. To reference the static functions in the different class ``UIF``, we put ``UIF.`` (with the dot) at the start of each reference to a static function in the class ``UIF``. .. warning:: In Xamarin Studio, if you use a file from a library project (without just copying the present version of that file into the current project), be sure that the current project includes a *reference* to the library project. If you expand the references in the Xamarin Studio project addition3, by clicking on the References line in the solution pad, you should see the project ui. Shortly you will see the optional section for making your own :ref:`library-projects-in-xamarinstudio`. Though we have not discussed all the C# syntax needed yet, there is also an improved class ``UI`` in the ui project that we discuss later. It includes all the function names in ``UIF``, and keeps your program from bombing out if the user enters an illegal format for a number. .. index:: documentation of functions function; documentation /// single: /// documentation .. _function-documentation: Function Documentation ---------------------- In keeping with :ref:`Two-Roles`, in future you will be a *consumer* of the library classes. It is particularly important to document library classes with the interface information users will need. Documentation could be written in a separate document, but much developer history has shown that such documentation does not tend to either get written in the first place, or not updated well to stay consistent with updates in the code. Inconsistent documentation is useless. Documentation is much more likely to be seen and maintained by the implementers if it sits right with the code, like our comments before the class and function headings. You will note that instead of the usual line comment syntax ``//``, we have added an extra ``/``, making ``///``. That will also start a comment. (The third ``/`` is technically just a part of the comment.) There is a special reason for the notation: Though it is convenient for the *implementer* of code to have the documentation right with the code, a *user* of the functions only needs the interface information found in good documentation. The ``///`` lines before heading are specially recognized by *separate* automatic documentation generating programs. There are many documentation generating programs and conventions. For now we will just use plain text in the ``///`` lines. This is recognized by the Xamarin Studio system. If you open our ``examples`` solution, in Xamarin Studio, and edit window for :repsrc:`addition3/addition3.cs`, you can place your mouse over ``UIF`` and a popup window shows the ``UIF`` class heading documentation. If you move the mouse over ``PromptInt``, you should see the popup label showing the function signature and the function documentation. If you change the two ``///`` lines in ``uif.cs`` above the ``PromptInt`` heading to start with just ``//``. you should no longer be able to see the documentation part of the popup for ``PromptInt`` in the ``addition3.cs`` edit window. (Be sure to change back to ``///``.) There are more elaborate documentation conventions that can be used for Xamarin Studio and other documentation generation programs, not discussed here. This documentation also works inside a single program file. If you have a long program with lots of functions defined, this can also be helpful when calling one of your own functions. You can avoid jumping around to be reminded of the signature and use of your functions. .. _library-projects-in-xamarinstudio: Library Projects in Xamarin Studio (Optional) ------------------------------------------------ Xamarin Studio has a multi-step process for creating a library project and for separately referencing it in other projects. The *advantage* of this approach is when you want to change the implementation but not the interface to library functions, you just do it once, in the library project. Other projects reference that project. Some students find the Xamarin Studio overhead of setting up and referencing library projects onerous. As a practical matter with files that you want to reuse but are not likely to change, you can just copy the source file into the new project, and avoid the Xamarin Studio library setup overhead. Many of our already created example projects use a library version of UIF and several other utility files. You can do the same with your solutions, following the instructions below, or you can just copy in the needed utility files for each project. Hence the rest of the section here is *optional*: Try adding a reference yourself. Follow these instructions: #. In your own Xamarin Studio solution, start to add a project, but *instead* of leaving Console Project selected in the dialog window, select **Library Project**. #. Then add the project name ui, and continue like when starting previous projects. #. Copy in the ``.cs`` files from our ui project, :repsrc:`uif.cs ` and :repsrc:`ui.cs `. Now you have your library project. #. Create another regular Console project, addition3, in your *same* solution, and copy in our :repsrc:`addition3/addition3.cs`, so that is the only file. .. warning:: Xamarin Studio remembers the last kind of project you created. That is fine when you are creating a sequence of Console projects. However, if you have just explicitly chosen to create a library project, the default for your next project will also be library, and really mess up your next Console project. You can fix such an error after the fact as described next. If you created a Library project by mistake, you can either start over from scratch using the wizard again, but concentrating on making a *Console* project this time, or you can change the current project settings options manually: - Double click on the project in the Solution Pad (if that does anything, or right-click it and select Options). An elaborate Project Options dialog window appears. - In the left pane under Build, select General. In the right pane, you problably see Compile Target: Library. Change Library to *Executable*. - Finally finish as in the first error fix discussed in :ref:`xamarinstudio-reminders`, so the Console is used for input and output. (You should already have the Project options displayed from the steps above.) #. In the Solutions pad, in your addition3 project, click on the References entry just inside the project. You should see that the project is automatically set up to reference System. #. Open the local menu for the References, and select Edit References. #. Click the Projects tab in the window that pops up. This limits the length of the list that you search. #. Possibly after scrolling down, find the recently made ui project and check the box beside it. #. Click OK in the bottom right corner of the window. Now look at the References again. You should see ui listed! #. Run your addition3 project. You only need to add a library project once, but every further project that needs it, must have a *reference* to the library project added. You might try another for yourself with the next exercise! Again this approach allows you to change the implementation of your library class in just one copy in one project, which can be referenced from many places. If you copy the file into different projects, and then decide the code needs to be updated, you are stuck *finding* and editing *all* the copies! Not good. Our library files uif.cs, ui.cs, and later fio.cs, should not be moving targets, so copying should not cause a problem. This may simplify your life, but the tradeoff is not getting used to using library references, which are useful in the larger scheme of things. .. _QuotientUIEx: Quotient UI Exercise --------------------------------- Create :file:`quotient_u_i.cs` by modifying :file:`quotient_return.cs` in :ref:`QuotientStringEx` so that the program accomplishes the same thing, but use the UIF class for all user input.