Opera 12.15 Source Code
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

tutorials.html 6.0KB

  1. <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
  2. "http://www.w3.org/TR/html4/loose.dtd">
  3. <html>
  4. <head>
  5. <link rel=stylesheet href="../coredoc.css" />
  6. <title>Opera Core: Tutorials</title>
  7. </head>
  8. <body>
  9. <h1>Opera Core: Tutorials</h1>
  10. $Id$
  11. <h2>The Core API: PortingInterfaces and WindowCommander</h2>
  12. <h3>Port Opera in just 200 days!</h3>
  13. <p><a href="http://wiki/cgi-bin/wiki/wiki.pl?Porting_Opera">On the
  14. Wiki</a> there is a summary of the estimates time it takes to port
  15. Opera to a new platform, based on the ports to Kyocera and PowerTV.
  16. The figures are probably guesstimates as much as estimates, but adding
  17. them up it comes out to between 110 and 170 man-days for a port of the
  18. full browser, not including customer extras.</p>
  19. <p>The core porting API consists of the Porting_Interfaces from the
  20. core toward the platform facilities, and the WindowCommander from the
  21. core to the platform-specific Opera UI. That is, porting Opera
  22. consists to a large part of implementing platform hooks and UI.</P>
  23. <p>This tutorial attempts to explain how to go about doing a port and
  24. also tries to explain how things hang together.</P>
  25. <h3>First steps</h3>
  26. <p>Choose a build environment and a unique all-uppercase platform name
  27. (eg, MSWIN, EPOC; I'll use just "P"). Create a directory platforms/p
  28. and a cvs module called p. Create platforms/p/features.h by copying
  29. one from some other platform and enable and disable the features you
  30. want. The complete list is in <a
  31. href="../../../core/vfunc.txt">core/vfunc.txt</a>.</p>
  32. <p>Create a project or Makefile and try to compile. When you run into
  33. trouble, add header files as appropriate or insert a platform #ifdef
  34. (there are plenty already). If you're nice you will put modifications
  35. in a file in your platform directory and include this from eg
  36. core/pch.h, and not modify the core code unless you have to.</P>
  37. <p>Iterate until your code compiles and you only have one link error:
  38. g_factory is undefined.</p>
  39. <h3>g_factory and OpFactory</h3>
  40. <p>The abstract class OpFactory defines methods that create instances
  41. of platform versions of abstract porting interfaces; the core code
  42. uses OpFactory to bootstrap itself into a particular platform setting.</p>
  43. <p>(OpFactory documentation is missing; see
  44. <a href="../../../Porting_Interfaces/OpFactory.h">Porting_Interfaces/OpFactory.h</a>.)</p>
  45. <p>The first thing you need to do is to define a global variable:
  46. <pre>
  47. OpFactory* g_factory = NULL;
  48. </pre>
  49. Then you subclass OpFactory with a platform-specific implementation
  50. class:
  51. <pre>
  52. class PlatformOpFactory : public OpFactory { ... };
  53. </pre>
  54. and define a method on the OpFactory class to create the platform-specific
  55. instance:
  56. <pre>
  57. OpFactory* OpFactory::Create()
  58. {
  59. return new WindowsOpFactory;
  60. }
  61. </pre>
  62. Depending on which features you have enabled, you must implement a number of
  63. the pure virtual methods of OpFactory.</p>
  64. <p>Once you've implemented the OpFactory you will have a bunch of
  65. methods that allocate instances of classes that do not
  66. exist--OpBitmap, OpFontManager, OpView, and so on. These must now be
  67. implemented by subclassing various Porting_Interface classes with
  68. platform-specific representations. Most of the Porting_Interfaces
  69. required by OpFactory are straightforward; just read the comments in
  70. the header files. OpView and OpWindow are more complicated,
  71. however.</p>
  72. <h3>OpView, OpWindow, and the OpWindowCommander</h3>
  73. <p>An OpView (<a
  74. href="../../../Porting_Interfaces/OpView.h">Porting_Interfaces/OpView.h</a>)
  75. represents an area for drawing. The area represented by the OpView
  76. may be larger than the area in which the drawing is displayed, so the
  77. OpView may have to be able to scroll. OpViews can be nested, but
  78. there is always an OpWindow around the outermost OpView.</p>
  79. <p>An OpWindow
  80. (<a href="../../../Porting_Interfaces/OpWindow.h">Porting_Interfaces/OpWindow.h</a>)
  81. represents a user interface window -- a container that
  82. the user perceives as being mostly independent of other windows.
  83. There are many kinds of windows--desktop windows, document windows,
  84. and dialog boxes to mention some--and some have ties to others, without
  85. this fact impinging on their window-ness. The OpWindow is itself not
  86. an area for drawing: OpViews nested in the window are used for
  87. drawing.</p>
  88. <p>For some kinds of windows the OpWindow and its nested views are all
  89. that's required, but this it is not sufficient for representing a
  90. regular browser window with its history, state, and so on. Browser
  91. windows are instead represented by a pair of objects: an OpWindow for
  92. the UI aspect and an OpWindowCommander (<a
  93. href="../../../modules/windowcommander/OpWindowCommander.h">modules/windowcommander/OpWindowCommander.h</a>)
  94. for the additional stuff. The OpWindowCommander presents a rich API
  95. that allows the UI to manipulate the browser window state.</p>
  96. <h3>Initialization</h3>
  97. <p>From your main() you need to create the OpFactory by calling
  98. OpFactory::Create and assigning the result to g_factory:
  99. <pre>
  100. g_factory = OpFactory::Create();
  101. </pre>
  102. Normally this is done very early, before any other Core code is used.</p>
  103. <p>The rest of core initialization is currently very messy. Some core
  104. initialization is always performed by the platform code, as this
  105. allows specialized initialization of some components, allows platform
  106. code to insert initialization actions in the middle of the core
  107. initialization sequence, or allows core initialization to be performed
  108. when the user interface is operational. Your only chance here is to
  109. look at an existing platform port to see how it's done.</p>
  110. <h3>The message loop</h3>
  111. <p>At some point during initialization there is a call to the Run method of
  112. the message loop:
  113. <pre>
  114. g_messageLoop->Run();
  115. </pre>
  116. after which Opera starts dispatching messages to installed message
  117. handlers. The message loop is an instance of OpMessageLoop, that is,
  118. it has a platform implementation created by the OpFactory. The loop
  119. does not return to its caller until Opera is ready to terminate, so it
  120. must itself process system messages.</p>
  121. </body>
  122. </html>