== API מקובל משותף ==

===עמודעימוד===[[Image:Doc_paper.png|left|thumb|400px]] תיאור התיאור ומאפייני הדף אליו יועבר תיצוג תצוג כל דוחבאשר הוא, מאוחסן על ידי אדגם [http://www.gramps-project.org/docs/ gen/gen_plug.html#gen.plug.docgen.paperstyle.paperstyle Classyle]. אדגם זה זמין דרך תכונת מחלקה <tt>basedoc.paper_style</tt>. סוג ה־PaperStyle שנבחר מועבר למחולל המסמכים בעת האתחול, ומטופל על ידי מסגרת פתוח הדוחות.

The רכיב <tt>PaperStyle</tt> holds information on the size of the paper מכיל מידע על גודל הדף ([http://www.gramps-project.org/docs/gen/gen_plug.html#gen.plug.docgen.paperstyle.PaperStyle מחלקה PaperSize class] instanceלדוגמה), the size of the margins, and the orientation of the paperגודל השוליים וכיוון הדף. Use the proper accessor methods to get the valuesכדי לקבל את הערכים יש להשתמש בשיטות העזר המתאימות. To get the metrics of the usable area of a paper כדי לקבל את תשקיל האזור בו ניתן להשתמש בדף (page without the marginsדף ללא שוליים) one can also use the אפשר גם להשתמש ב[http://www.gramps-project.org/docs/gen/gen_plug.html#gen.plug.docgen.paperstyleשיטות נוחות.PaperStyle.get_usable_width PaperStyle.get_usable_widthרוחב שמיש] and ו־[http://www.gramps-project.org/docs/gen/gen_plug.html#gen.plug.docgen.paperstyle.PaperStyle.get_usable_height PaperStyle.get_usable_heightגובה שמיש] convenience methods. Width and height are always given according to the orientation of the paper, thus width is always the horizontalרוחב וגובה מתקבלים תמיד לפי כיוון הנייר (לאורך או לרוחב), and height is always the vertical dimensionולכן הרוחב הוא תמיד הממד האופקי והגובה הוא תמיד הממד האנכי.

Text reports do not need to care about paper propertiesלדוחות מלל אין צורך לדאוג למאפייני דף, as the document generator שכן מחולל המסמכים (or the external viewerאו המשקף החיצוני) paginates the report according to those propertiesמספרר את הדוח בהתאם לאותם מאפיינים. Whileמאידך, on the other handדוחות חזותיים כן נדרשים להתחשב במאפייני הדף בעת יצירת רכיבים חזותיים, graphical reports do need to take paper properties into account when creating graphical elements, i.e. they should not draw on the marginsכלומר הם לא אמורים לגלוש לשוליים.<!--[[Image:gramps-devel.png|left|22px]] ''document generator should hide paper properies for graphical reports too'מחולל מסמכים צריך להסתיר גם מאפייני דף עבור דוחות חזותיים'--> The origin of the coordinate system is the top left corner of the usable area.

==מסמך API מילולי API==

The specification of the את מפרט ה־API לרכיב Textdoc API is ניתן למצוא בקישור הבא: [https://gramps-project.org/docs/gen/gen_plug.html#gramps.gen.plug.docgen.textdoc.TextDoc hereTextDoc]

The interface for adding media objects is as followsהמנשק להוספת עצמי מדיה הוא כדלקמן:

add_media_object(name, align, w_cm, h_cm, alt='', style_name=None, crop=None)[sourceמקור]</pre> Add a photo of the specified width </div>הוספת תמונה ברוחב שצוין (in centimetersבסנטימטרים). Parametersמשתנים: <div dir="ltr"> <pre> name – filename of the image to addשם קובץ התמונה אותה מעוניינים להוסיף&rlm; align – alignment of the imageיישור התמונה. Valid values are ‘left’, ‘right’ערכים תקינים הם 'שמאל', ‘center’'ימין', and ‘single’'מרכז' ו'יחיד'&rlm; w_cm – width in centimeters&rlm; רוחב בסנטימטרים h_cm – height in centimetersגובה בסנטימטרים alt – an alternative text to useמלל חלופי בו ניתן להשתמש. Useful for eg html reportsשימושי לדוגמה בדוחות HTML style_name – style to use for captionsשם הסגנון בו יעשה שימוש בכתוביות crop – image cropping parametersמשתנים לחיתוך תמונה

Note that because of the structure of these documents, Images are only allowed as children (i.e. following) Document or Cell. This interface is used in the following reportsמנשק זה משמש בדוחות הבאים: {| {{Prettytable}}

! Reportדוח! Built-inסוג! alignיישור! style_nameשם סגנון! how calledאופן קריאה

| Detailed Ancestral Reportדו"ח אבות־קדמונים מפורט| Built-inמובנה| rightימין

| via על־ידי gen/plug/report/utils.py

| Detailed Descendant Reportדוח צאצאים מפורט| Built-inמובנה| rightימין

| via על־ידי gen/plug/report/utils.py

| Individual Complete Reportדוח אישי מלא| Built-inמובנה| rightימין| Noneללא| directיָשִׁיר

| Book ספר דוחות (Title Pageעמוד השער)| Built-inמובנה| centerמֶרְכָּז| Noneללא| directיָשִׁיר

| Person Everythingדוח אדם כולל| Addonתוסף| singleיחיד

| directיָשִׁיר

None of the reports use הדוחות הללו לא משתמש במלל חלופי 'alt'. It is understood (from looking at the code in odfdocמבחינת שורות הקוד ב־odfdoc.py) that ברור כי יישור ל'''leftשמאל''' and ול'''rightימין''' alignment should cause the text to wrap around the media objectאמור לגרום למלל להתעטף סביב לעצם המדיה, while for בעוד שליישור '''singleיחיד''' alignment, there should be no text on either side of the media object. Since style_name should be used as the style for the caption (i.e. the '''alt''' string) it should also be used for the image itself. Otherwise the caption would not be below the pictureלא אמור להיות מלל משני הצדי עצם המדיה.

As at December 2014מכיוון ש־style_name צריך לשמש כסגנון עבור הכתובית (כלומר מחרוזת '''alt'''), output appears as follows:יש להשתמש בו גם עבור התמונה עצמה. אחרת הכתובית לא תופיעה מתחת ובצמוד לתמונה.<br>

! Formatתסדיר! rightימין! centerמרכז! singleיחיד

| '''OKבסדר''' Picture on rightתמונה מימין, text wrapped round itמלל עטוף סביבה

| Picture on left marginתמונה בצמוד לשוליים השמאליים, text not wrappedמלל לא עטוף

| Picture on left marginתמונה בצמוד לשוליים השמאליים, text not wrappedמלל לא עטוף

| '''OKבסדר''' Picture aligned with previous paragraphתמונה מיושרת לפסקה הקודמת, text not wrappedמלל לא עטוף

| '''OKבסדר''' Picture on rightתמונה מימין, text wrapped round itמלל עטוף סביבה

| Picture centredהתמונה ממורכזת, text not wrappedמלל לא עטוף

| Picture on rightתמונה מימין, text not wrappedמלל לא עטוף

| Picture on left marginתמונה בצמוד לשוליים השמאליים, text not wrappedמלל לא עטוף