feature: Table.direction

[cheshirex]

Can you add support for making text (runs, I suppose, although I'd like to be able to set it at the document level also) and tables right-to-left?

Thanks!

[danmilon]

See the rtl flag on the run object.

[cheshirex]

Thanks, sorry, I'm not sure how I missed that when looking over the documentation (I specifically searched for both "rtl" and "bidi" -- guess I must have mistyped it). Is there something similar for table direction? (i.e. so that the first cell in the row is on the right side, not the left)

[danmilon]

I'm not aware of such an option. You can look into the open xml specification or here and see if such an option exists. If so, we can port it as an option on the library.

[cheshirex]

Looking at the open xml spec referenced, it's listed in part 1, paragraph
17.4.1.

Basically, in the table parameters section "<w:tblPr>", adding a
"<w:bidiVisual/>" element causes the table to be ordered right-to-left. I
verified this against a document that I have locally with such a table.

Thanks!

[danmilon]

Indeed, there is some bidiVisual in the code, but it does not seem fully implemented.

I think my knowledge ends somewhere here :)

[scanny]

@cheshirex I'm not familar with righ-to-left (RTL) language conventions. Is BiDi the only kind of RTL there is (i.e. is synonymous with RTL) or is it one of some number of varieties?

@danmilon is correct that it appears in the code base, but all essentially as part of analysis documentation so far.

This one is probably one of the easiest features to add, as features go. If we can get the required analysis sorted out enough to specify the API we can probably drop it in for you in the next release, and probably whip up a workaround function to hold you over in the meantime.

[cheshirex]

@scanny, it's all part of the same terminology. "BiDi" is short for "BiDirectional", of which the options are LTR (left-to-right, most languages) and RTL (right-to-left, languages like Hebrew and Arabic).

That would be great. Thanks!

[scanny]

Ah, ok, that makes sense now :)

The MS API has the property Table.TableDirection which can be one of wdTableDirectionLtr or wdTableDirectionRtl. It sounds like we could add a property Table.table_direction with enumerated values WD_TABLE_DIRECTION.LTR and .RTL that should do the trick.

Do you just need to set the property for now or will you need to read it as well? The reason I ask is the workaround function for setting it is quite a bit easier than the one for reading it.

[cheshirex]

I just need to write it. I'm generating a document that has tables in Hebrew. I don't need to read it, at least not with the project I'm currently working on.

[scanny]

Hi @cheshirex, apologies for the delay in getting to this ...

This should get it done:

from docx.oxml import OxmlElement
from docx.oxml.ns import qn

def first_child_found_in(parent, tagnames):
    """
    Return the first child of parent with tag in *tagnames*, or None if
    not found.
    """
    for tagname in tagnames:
        child = parent.find(qn(tagname))
        if child is not None:
            return child
    return None

def insert_element_before(parent, elm, successors):
    """
    Insert *elm* as child of *parent* before any existing child having
    tag name found in *successors*.
    """
    successor = first_child_found_in(parent, successors)
    if successor is not None:
        successor.addprevious(elm)
    else:
        parent.append(elm)
    return elm

tblPr = table._tblPr  # tblPr is the <w:tblPr> XML element
tblPr = tbl.tblPr
bidiVisual = OxmlElement('w:bidiVisual')
bidiVisual.set(qn('w:val'), 'on')
insert_element_before(tblPr, bidiVisual, successors=(
    'w:tblStyleRowBandSize', 'w:tblStyleColBandSize', 'w:tblW', 'w:jc',
    'w:tblCellSpacing', 'w:tblInd', 'w:tblBorders', 'w:shd', 'w:tblLayout',
    'w:tblCellMar', 'w:tblLook', 'w:tblCaption', 'w:tblDescription',
    'w:tblPrChange'
))

Note that this code makes a number of assumptions, in particular that there is no <w:bidiVisual> element present yet. But it should work fine for newly generated tables.

Let me know if it gives you any trouble.

I'll leave this issue open as a feature request to get a proper version into the build.

[scanny]

Added in release v0.8.5, pushed on Feb 21, 2015.