Work at SourceForge, help us to make it a better place! We have an immediate need for a Support Technician in our San Francisco or Denver office.

Close

Hello World! Beginners source inspection

2009-11-20
2013-01-26
  • Experienced in Java and program design, interested in a good PDF programmering tool, I must say I find the Clown code very hard to get to know.
    At the beginners stage very simple examples would be extremely useful, especially since other *starters documentation* seems to be scarce with the Clown project.
    Even "Hello World" resisted inspection. It seems to be dependent on SampleLoader which again depended on not only abstractactions and reflection, but even on files and directory structures.
    Starting "Hello World" examples with code archeology, file system inspection and  even fruitless debugging is simply too much.
    What I need now to open Clown again, is a successfull "following level" instruction. I'm not interested in command line tools, but to see working code in action in my own tool (Eclipse). At least for the simplest of all: "Hello World"

     
  • Hi Viggo,

    *your considerations about the current lack of a 'Getting started'-like guide for beginners are appropriate* (I'll manage to make available such a document for the next release), *but your difficulties about inspecting and debugging the HelloWorldSample are quite strange* (especially considering that you qualify yourself as "experienced in Java and program design").

    Let me explain: in order to bring to the user only the relevant code isolating it from boiler-plate, redundant operations (such as input file selection, output file writing and so on) which would have messed the things up (as typically occurs with several code samples from other projects - I hate 'em!) without adding any value, I managed to define a **minimal plugin-based infrastructure** which dynamically discovers classes implementing the ISample interface (i.e. the actual samples). The engine of such ridiculously simple infrastructure is SampleLoader. Furthermore, it's just a matter of facts that if samples need input PDF files in order to do any significant demonstration, we have to depend on files and directory structures (can you do it differently, uh? ;-) ), but that's really trivial as the mechanism is based on a standard, plain old 'properties' configuration file (PDFClownSamples.properties)!

    I don't think that's "code archeology" to dig just 1 level of abstraction, when such level results in an overall benefit for the clarity of the sample code. You DON'T need to investigate the reflective mechanism used to collect the sample classes: just concentrate on the sample (after all, abstraction principle's aim is merely to let you ignore lower level operations which don't add value to your comprehension in your current scope)!

    You say that you are "not interested in command line tools": I totally agree with you! The problem is that *you are wrongly focusing your attention on the sample infrastructure* (i.e. the medium through which I expose code samples), *instead of the actual samples!* you are unusefully jumbling up the means with the objectives! I just needed a simple, economic way to expose my code samples: I could have projected the output PDF files into a 3D OpenGL rendering scene (it would have been really fancy!), but I think it would have been a little bit outside the scope of this project… :-D

    *I assure you that PDF Clown and its code sample projects work smoothly inside the Eclipse environment* (I successfully tested them on Eclipse 3.5 Galileo), you just have to ensure the ANT files (build.xml) are appropriately activated when building operations are triggered. Anyway, to ease the life of Eclipse users, I will ship the next release with a step-by-step tutorial to the use of PDF Clown in Eclipse.

    So, I thank you for expressing the need for a friendlier introduction to the use of the library - it'll also help to avoid unpleasant misunderstandings. :-)

    Stefano

     


  • 2010-05-04

    Hi Stefano,

    If I may respectfully contribute to this discussion (given that it took place 6 months ago), I would like to say that I can see this from both sides.  I agree with you that there is a lot of mostly boilerplate code that is needed to implement both PDF files and a series of tutorial examples, and that learning that boilerplate is a stumbling block to getting things done.  Having samples that build upon each other (like yours do) helps us library users to learn how the library features are meant to be used to accomplish the demonstrated effect.  But as a new user I can understand vholmstedt's frustration as well.  Frameworks in general are hard to learn.  You can look at a call in a program and ask what the parameters mean.  It is much harder to understand what is going on in a class that has inherited from a framework.  It does help a newbie to see how simple it can be with all the code in a main() and no dependencies other than the library.  For example, the helloworld.cs can contain just the following pasted inside main and you get a PDF that will display properly:

        File file = new File();
        Document document = file.Document;
        PrimitiveFilter builder = new PrimitiveFilter(page);
        builder.SetFont(
            new StandardType1Font( document,
                StandardType1Font.FamilyNameEnum.Courier, true, false),
            32);
        builder.ShowText("Hello World!", new PointF(32,48));
        builder.Flush();
        file.WriteTo("HelloWorld.pdf", SerializationModeEnum.Standard);
    

    Once we see what seven lines of code can do we can start learning everything else.

     


  • 2010-05-04

    Oops, managed to lose two lines while pasting.  Here is the code that will work:

        File file = new File();
        Document document = file.Document;
        Page page = new Page(document);
        document.Pages.Add(page);
        PrimitiveFilter builder = new PrimitiveFilter(page);
        builder.SetFont(
            new StandardType1Font( document,
                StandardType1Font.FamilyNameEnum.Courier, true, false),
            32);
        builder.ShowText("Hello World!", new PointF(32,48));
        builder.Flush();
        file.WriteTo("HelloWorld.pdf", SerializationModeEnum.Standard);
    
     
  • john murray
    john murray
    2011-08-31

    I hesitate to revive this thread - I too am a beginner and am having enormous  difficulties just trying to understand how to start the Hello World example - looking through all the responses it seems I can expect a response of 'well if you're too stupid or inexperienced to understand it you don't deserve a response!!! Sorry Steffan but that's how you come across in your responses.

    There is no sin in not knowing and I am asking very politely- is there a simple example where l can put up a form (windows c# vis studio) using the library and examples - implement a button click and show a pdf or create a simple hello world pdf on screen.?  - that would get me started -
    I think Stefan in one of you 2008 responses you said it was a good idea but not a priority as you had a life to lead - I total appreciate the cleverness of what you've done and the effort you've put in and I want to use it - but like many others I need more help.and also have a life to lead.

    one issue is probably that I am trying to implement a gui hello world in VS2010 whereas the example code is designed for a command line implementation - the pdfclown.samples.gui only exists in the java examples and I can only barely open eclipse let alone use it seriously.
    Finally sorry to seem a complainer Steffan, after the huge effort you've put in -
    I have a real project which could seriously use this and I am only trying it to explore possibilities - other clever people will do the spade work. I know you have done much work for free and applaud you for that - are you available to help a gimp such as me for some financial return? can we communicate off public line?

     
  • hi John,
    if you skimmed through the project's source code (including the code samples) you should have observed how many comment lines it's filled with, as I keep in great consideration and respect users… but I cannot nurse them! ;-)
    I still cannot understand what's the difficulty about launching a dumb console application in, say, Visual Studio just to try and evaluate some code samples (you don't need a GUI for that!); after you have explored that code running, you can transfer the pieces you want into your bells-and-whistles GUI application. Can you explain me what's the paramount difference between clicking a button and choosing a console option just to execute the *same* sample code?
    So, let's examine the "overcomplex" HelloWorldSample which is part of the PDF Clown distribution (see below): it has a Run method which (as you can guess) is invoked automatically to run the code sample. This method features a well-defined series of steps to basically illustrate how PDF Clown works:
    1. instantiation of a new PDF file;
    2. getting of corresponding PDF document;
    3. insertion of contents into the document;
    4. serialization of the file: this operation is inherited from the Sample class (again, see the pdfclown.sample.cli project included in the PDF Clown distribution) because it's reused across all the 40+ CLI samples - for the sake of simplicity, here it is its actual (no-brainer) content: file.Save(outputFilePath, serializationMode)
    I keep asking myself: what's the difficulty in that???

    using org.pdfclown.documents;
    using org.pdfclown.documents.contents.composition;
    using org.pdfclown.documents.contents.fonts;
    using org.pdfclown.files;
    using System.Drawing;
    namespace org.pdfclown.samples.cli
    {
      /**
        <summary>This sample is a minimalist introduction to the use of PDF Clown.</summary>
      */
      public class HelloWorldSample
        : Sample
      {
        public override bool Run(
          )
        {
          // 1. Instantiate a new PDF file!
          /* NOTE: a File object is the low-level (syntactic) representation of a PDF file. */
          File file = new File();
          // 2. Get its corresponding document!
          /* NOTE: a Document object is the high-level (semantic) representation of a PDF file. */
          Document document = file.Document;
          // 3. Insert the contents into the document!
          Populate(document);
          // (boilerplate metadata insertion -- ignore it)
          BuildAccessories(document,"Hello world","a simple 'hello world'");
          // 4. Serialize the PDF file!
          Serialize(file,false);
          return true;
        }
        /**
          <summary>Populates a PDF file with contents.</summary>
        */
        private void Populate(
          Document document
          )
        {
          // 1. Add the page to the document!
          Page page = new Page(document); // Instantiates the page inside the document context.
          document.Pages.Add(page); // Puts the page in the pages collection.
          // 2. Create a content composer for the page!
          PrimitiveComposer composer = new PrimitiveComposer(page);
          // 3. Inserting contents...
          // Set the font to use!
          composer.SetFont(
            new StandardType1Font(
              document,
              StandardType1Font.FamilyEnum.Courier,
              true,
              false
              ),
            32
            );
          // Show the text onto the page!
          /*
            NOTE: PrimitiveComposer's ShowText() method is the most basic way
            to add text to a page -- see BlockComposer for more advanced uses
            (horizontal and vertical alignment, hyphenation, etc.).
          */
          composer.ShowText(
            "Hello World!",
            new PointF(32,48)
            );
          // 4. Flush the contents into the page!
          composer.Flush();
        }
      }
    }
    

    If you still have any doubt please be more specific and precise (if you could also take a little bit more care with spelling correctly my name I'd be really happy, thank you!)
    Stefano